Create a server app package

When you submit your app for approval to list on the Marketplace, you provide a JAR file that contains your code and visual assets. The Marketplace parses your JAR, verifying it contains required metadata for approving and listing your app. This file is also used by the Universal Plugin Manager (UPM) to ensure your app is compatible with Atlassian host products like Jira or Confluence.

This page describes key metadata properties and files used by UPM and the Marketplace.

Key files in your submission

Your JAR submission should include the project object model file pom.xml, the atlassian-plugin.xml file to describe dependencies, and a atlassian-plugin-marketing.xml file, all in addition to the JAR manifest. When you use the SDK atlas-create* commands, you supply the command with parameter values, and the generator populates corresponding parameters in the pom.xml. The atlassian-plugin.xml descriptor file references these values, and the atlassian-plugin-marketing.xml describes your visual marketing assets to the Marketplace. The JAR manifest file contains properties key to your submission.

As you write your code, you can edit the metadata in these files either manually or through the SDK generations tools. Values you specify include:

• key
• organization name
• visual resources such as logos, icons, and screenshots
• version

When you use the SDK to generate your project JAR, the generator creates a version of the descriptor file that is read by Atlassian systems. The generated JAR also gets a manifest with some key properties.

When you list an app with the Atlassian Marketplace, the Marketplace submission form asks you to enter many of the same values again. The submission form also asks you for a deployable JAR. Both the Marketplace and UPM use a combination of your submission values and your metadata files to display your listing to your customers. To give your customers a consistent experience with your listing in the Marketplace and UPM, make sure the values you provide in your metadata files and your submission are the same.

pom.xml file

The pom.xml file contains several parameters that describe your app. The SDK's code generation commands populate these parameters or you can edit them manually. The atlassian-plugin.xml file references these parameters. The pom.xml values that identify your app and organization appear at the top of the POM:

1
2
<modelVersion>4.0.0</modelVersion>
<groupId>com.example.plugins.tutorial</groupId>
<artifactId>tutorial-plugin-marketing</artifactId>
<version>1.0-SNAPSHOT</version>

<organization>
    <name>Example Company</name>
    <url>http://www.example.com/</url>
</organization>

<name>tutorial-plugin-marketing</name>
<description>This is the com.example.plugins.tutorial:tutorial-plugin-marketing plugin for Atlassian Jira.</description>
<packaging>atlassian-plugin</packaging>

The fields that identify which product versions your app supports are near the bottom in the properties stanza:

1
2
<properties>
    <amps.version>3.7.2</amps.version>
    <confluence.data.version>3.5</confluence.data.version>
    <confluence.version>4.0</confluence.version>
</properties>

In this example, the confluence.version value marked as compatible with the appropriate product version, i.e. the product versions in which UPM can manage your app.

atlassian-plugin.xml descriptor file

Describes a app and the modules contained within it. More complex apps have complex descriptor files. There are specific attributes and param elements contained in the descriptor file that are important to your submission. You can use these param elements to define your marketing assets. You can also use param elements to define additional configuration or support pages in your app. The following example shows how to do this:

1
2
<atlassian-plugin key="${project.groupId}.${project.artifactId}" name="${project.name}" plugins-version="2">
    <plugin-info>
        <description>${project.description}</description>
        <version>${project.version}</version>
        <vendor name="${project.organization.name}" url="${project.organization.url}" />

        <param name="plugin-icon">images/pluginIcon.jpg</param>
        <param name="plugin-logo">images/pluginLogo.jpg</param>
        <param name="plugin-banner">images/pluginBanner.jpg</param>
        <param name="vendor-icon">images/vendorIcon.jpg</param>
        <param name="vendor-logo">images/vendorLogo.jpg</param>
    </plugin-info>
    ...

</atlassian-plugin>

The following table lists important metadata attributes or elements in this file:

The following table lists marketing-related param elements for your file:

Provide these marketing assets as resources within your code. For example, for a plugin-icon path of images/pluginIcon.gif, you place your image within in the src/main/resources/images/pluginIcon.gif folder.

The following table lists url-related param elements for your file:

If you supply one of the URL param elements, keep in mind the URL represents a servlet or action module defined in your app code. The URL value is the module's location relative to the host product's base URL. For example, if your configuration options are edited through a servlet in Jira, your specify a URL relative to a base URL similar to this http://myhost.local:2990/jira/plugins/servlet.

A app can have both a post.install.url and a post.update.url. UPM displays the post.install.url when the app is first installed. The post.update.url only appears when the app is updated. UPM only uses these parameters if the user installed the app using the Free Trial or Buy Now buttons or updated it using the Update button. If a customer downloads an app JAR and uses the Upload Plugin installation technique, UPM ignores these parameters.

UPM always uses the configure.url parameter regardless of how a user installs an app.

post URL Parameter Support in UPM

The post.install.url and post.update.url require UPM 2.3 or higher. If an app defines these URLs but is installed or updated within a UPM 2.2 instance or earlier, they are ignored.

atlassian-plugin-marketing.xml file

This file is used only for marketing resources on Atlassian Marketplace listings. You can create this file under src/main/resources in your app JAR to reference visual assets used on the Atlassian Marketplace. This file should reference images in an images directory for your app JAR, like the following: 

1
2
<atlassian-plugin-marketing>
       
      <!--Describe names and versions of compatible products -->
      <compatibility>
        <product name="jira" min="4.0" max="4.4.1"/>
        <product name="bamboo" min="3.0" max="3.1"/>
      </compatibility>
       
      <!-- Describe your app logo and banner. The banner is only displayed in the UPM. -->
      <logo image="images/01_logo.jpg"/>
      <banner image="images/02_banner.jpg"/>
       
      <!-- Describe highlight and cropped highlight image assets, in order. -->
      <highlights>
        <highlight image="images/03_highlight1_ss.jpg" cropped="images/04_highlight1_cropped.jpg"/>
        <highlight image="images/05_highlight2_ss.jpg" cropped="images/06_highlight2_cropped.jpg"/>
        <highlight image="images/07_highlight3_ss.jpg" cropped="images/08_highlight3_cropped.jpg"/>
      </highlights>
       
      <!-- Describe additional screenshots you'd like listed on your app listing. -->
      <screenshots>
        <screenshot image="images/09_addl_ss1.jpg"/>
        <screenshot image="images/10_addl_ss2.jpg"/>
        <screenshot image="images/11_addl_ss3.jpg"/>
      </screenshots>
  
</atlassian-plugin-marketing>

When you upload your app for approval, the Marketplace parses this file for assets to display on your app details page. The below assets can be packaged in your JAR. To view complete branding assets required, see Build your presence on Marketplace.

JAR manifest

Except in advanced situations, you should not need to edit or alter the META-INF/MANIFEST.MF file within your JAR. The Atlassian Plugin SDK generates the minimum necessary information in the manifest for you. If you do edit the manifest for any reason, be aware that it contains OSGI instructions that are necessary for proper functioning within the plugin framework; see OSGi, Spring and the Plugin Framework.

Finally, the SDK commands generate an Atlassian-specific property in the JAR manifest--the Atlassian-Build-Date property. This is the date that the JAR was built, and it has a format of yyyy-MM-ddTHH:mm:ssZ. The following example illustrates a generated manifest with this property:

1
2
Manifest-Version: 1.0
Archiver-Version: Plexus Archiver
Created-By: Apache Maven
Built-By: manthony
Build-Jdk: 1.6.0_31
Atlassian-Build-Date: 2012-05-08T17:01:14-0700

If your app uses the Atlassian licensing API, make sure you do not remove the Atlassian-Build-Date property. The licensing system uses the property to determine whether a new version of an app is too new to be supported by an existing license. If you find that this property is not appearing in your manifest, you may be using an obsolete version of the Atlassian SDK.