Plugin metadata files used by UPM and Marketplace

When you submit your add-on 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 add-on. This file is also used by the Universal Plugin Manager (UPM) to ensure your add-on is compatible with Atlassian host applications like JIRA or Confluence. 

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

File Purpose Assets described or defined

Descriptor file

atlassian-plugin.xml

Describes your add-on and marketing material to Atlassian host applications and UPM.

Reference SDK documentation or read more below.

  • Plugin component modules
  • Vendor icon
  • Vender logo
  • Add-on banner
  • Add-on logo
  • In-application visual assets (icons for macro menus, etc)

Visual marketing descriptor

atlassian-plugin-marketing.xml

Describes visual marketing assets to the Atlassian Marketplace. This file is only used for Atlassian Marketplace listings.

Read more below.

  • Add-on logo
  • Add-on banner
  • Add-on highlight screenshots, including cropped versions
  • Additional add-on screenshots

pom.xml

Defines add-on dependencies.

Reference SDK documentation or read more below.

  • Vendor name
  • Vendor website
  • Add-on name
  • Add-on description

JAR Manifest

MANIFEST.mf

Read more below.
  • The build date property

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 add-on 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.

The pom.xml file

The pom.xml file contains several parameters that describe your plugin. 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 add-on and organization appear at the top of the POM:

    <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 add-on. Together with the groupId, this value forms your plugin key. 

version

The version of your add-on. 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 add-on name. Your add-on 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 add-on.

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

<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 plugin.

The atlassian-plugin.xml descriptor file

Describes a plugin and the modules contained within it. More complex plugins 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 plugin. The following example shows how to do this:

<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 add-on 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

Description

vendor-icon

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.
Length/Size: 16x16px PNG/JPG/GIF (Animated GIFs are not allowed.)

vendor-logo

Specifies a large, clear, front-facing image. The logo appears on the add-on detail page and potentially in our featured tab. The logo should be relevant to your vendor name.
Length/Size: 72x72px PNG/JPG/GIF (Animated GIFs are not allowed.)

plugin-logo

Specifies a large, clear, front-facing logo. This logo appears on the add-on 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.
Length/Size: 144 x 144px PNG/JPG

plugin-banner

Specifies a catchy but relevant add-on banner, complete with a brief marketing message outlining what your add-on does, attractive visuals, and the full name of your company and add-on. If your add-on 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.
Length/Size: 1120 x 548px PNG/JPG for high-resolution images or 560 x 274px PNG/JPG for standard images

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 add-on that allow users to configure options for the plugin. Supported by all types of add-ons.

post.install.url

Specifies a page that appears after add-on installation finishes. This can be identical to the configure.url parameter or not. For example, this page can contain getting started information for your plugin. Support only for Marketplace paid add-ons.

post.update.url

Specifies a page that appears after an add-on 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 add-ons.

If you supply one of the URL param elements, keep in mind the URL represents a servlet or action module defined in your plugin code. The URL value is the module's location relative to the host application'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 plugin can have both a post.install.url and a post.update.url. UPM displays the post.install.url when the plugin is first installed. The post.update.url only appears when the plugin is updated. UPM only uses these parameters if the user installed the plugin using the Free Trial or Buy Now buttons or updated it using the Update button. If a customer downloads an add-on 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 a plugin.

post URL Parameter Support in UPM

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

The 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 add-on JAR to reference visual assets used on the Atlassian Marketplace. This file should reference images in an images directory for your add-on JAR, like the following: 

<atlassian-plugin-marketing>
       
      <!--Describe names and versions of compatible applications -->
      <compatibility>
        <product name="jira" min="4.0" max="4.4.1"/>
        <product name="bamboo" min="3.0" max="3.1"/>
      </compatibility>
       
      <!-- Describe your add-on 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 add-on 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 plugin for approval, the Marketplace parses this file for assets to display on your add-on 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

Description

plugin-logo

Specifies a large, clear, front-facing logo. This logo appears on the add-on 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.
Size: 144 x 144px PNG/JPG

plugin-banner

Specifies a catchy but relevant add-on banner, complete with a brief marketing message outlining what your add-on does, attractive visuals, and the full name of your company and add-on. If your add-on 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.
Size: 1120 x 548px PNG/JPG for high-resolution images or 560 x 274px PNG/JPG for standard images

compatibility Specifies the product name, minimum and maximum product compatibilities.  
highlights

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.

Size for each image: 1840 x 900px PNG/JPG or 920 x 450px PNG/JPG for standard images

Size for each cropped screenshot: 580 x 330px PNG/JPG

screenshots

Specify up to five additional screenshots.

Size: 1840 x 900px PNG/JPG or 920 x 450px PNG/JPG for standard images

The 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:

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 add-on 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 a plugin 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.

Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport