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>

Field
Description
groupId
This is typically a identifier that is unique to an organization or project. It may or may not use a dot format, such as com.atlassian.plugins.tutorial.
artifactId
A descriptive identifier for your app. Together with the groupId, this value forms your app key. 
version
The version of your app. This can be no more than 5 numbers. The version number must match what you specify on the Marketplace submission form.
organization.name
The name is the name of your organization as it appears in the Atlassian Marketplace.
organization.url
The url is the your organization website location.
name
Your app name. Your app name should be 40 characters or less, and must not contain any of the following words or names:

Atlassian
plugin
plug-in
add-on
addon
free
paid
your vendor name

description
A short description of your app.
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:
Attribute/element
Description
key
References and concatenates of the groupId and artifactId from the pom.xml.
name
References the app name from the pom.xml.
description
References the description from the pom.xml.
version
References the version from the pom.xml.
vendor.name
References the organization.name from the pom.xml.
vendor.url
References the organization.url from the pom.xml.
The following table lists marketing-related param elements for your file:
Parameter Name
Dimensions
Description
vendor-icon
16x16px PNG/JPG/GIF (Animated GIFs are not allowed.)
Specifies a smaller version of your vendor logo. This appears in the sidebar and top-ranked lists. If your logo does not scale down well, you may create an additional thumbnail image.
vendor-logo
72x72px PNG/JPG/GIF (Animated GIFs are not allowed.)
Specifies a large, clear, front-facing image. The logo appears on the app detail page and potentially in our featured tab. The logo should be relevant to your vendor name.
plugin-logo
144 x 144px PNG/JPG
Specifies a large, clear, front-facing logo. This logo appears on the app detail page and potentially on our featured tab. We strongly recommend a chiclet-style background for the logo (check out this free Photoshop template), as this will work best with upcoming changes to the user interfaces of UPM and the Atlassian Marketplace.
plugin-banner
1120 x 548px PNG/JPG for high-resolution images or 560 x 274px PNG/JPG for standard images
Specifies a catchy but relevant app banner, complete with a brief marketing message outlining what your app does, attractive visuals, and the full name of your company and app. If your app has a high number of downloads, this banner may be displayed on the Atlassian Marketplace homepage in the future. Do not include temporary promotion offers here.

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:
Parameter Name
Description
configure.url
Specify internal links within the app that allow users to configure options for the app. Supported by all types of apps.
post.install.url
Specifies a page that appears after app installation finishes. This can be identical to the configure.url parameter or not. For example, this page can contain getting started information for your app. Support only for Marketplace paid apps.
post.update.url
Specifies a page that appears after an app update finishes. For example, you could use this page to deliver "What's New in this Version" information to a customer. Support only for Marketplace paid apps.
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.
Parameter Name
Dimensions
Description
plugin-logo
144 x 144px PNG/JPG
Specifies a large, clear, front-facing logo. This logo appears on the app detail page and potentially on our featured tab. We strongly recommend a chiclet-style background for the logo (check out this free Photoshop template), as this will work best with upcoming changes to the user interfaces of UPM and the Atlassian Marketplace.
plugin-banner
1120 x 548px PNG/JPG for high-resolution images or 560 x 274px PNG/JPG for standard images
Specifies a catchy but relevant app banner, complete with a brief marketing message outlining what your app does, attractive visuals, and the full name of your company and app. If your app has a high number of downloads, this banner may be displayed on the Atlassian Marketplace homepage in the future. Please do not include temporary promotion offers here.
compatibility
 
Specifies the product name, minimum and maximum product compatibilities.  
highlights
1840 x 900px PNG/JPG or 920 x 450px PNG/JPG for standard images


580 x 330px PNG/JPG (cropped)
Specify each highlight with references to screenshots and cropped versions of each. List these references in order - the first listed will correspond to the first highlight.
screenshots
1840 x 900px PNG/JPG or 920 x 450px PNG/JPG for standard images
Specify up to five additional screenshots.
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.
Rate this page:
Unusable
Poor
Okay
Good
Excellent