First we have to make sure our Windows system has the prerequisite software and is configured correctly. The Atlassian SDK relies on Version 1.6.x or higher of the Oracle JDK.

To install the Oracle JDK, perform the following steps:

Now that you have the JDK installed on your system, add the JAVA bin directory to your path to ensure that you can use Java from the command prompt. Again, we assume a Windows setup.

To add JAVA_HOME to your path, perform the following steps:

Before we continue, we have to make sure the JDK is installed correctly so that the Atlassian SDK is able to use it.

To verify your JDK installation, perform the following steps:

When building a plugin for Confluence, the application will be running on your desktop. For Confluence to be able to start, it assumes port 1990 is available. On most machines this would not be an issue.

Verify your port numbers by performing the following step:

If the preceding command doesn't return anything, the port is available. If the preceding command does return something, port 1990 is already being used by another application. The Atlassian SDK will notice this during startup and assign a different port to Confluence. We will go into this in the Building, installing, and running your plugin section.

With all the prerequisites installed, we can download and set up the Atlassian SDK.

The Atlassian Plugin SDK is now installed and we are ready to create our first plugin.

To verify that the SDK is configured correctly, perform the following step:

When you want to build a new plugin, you need to create a plugin skeleton. Open a command prompt and run the following command in the location where you want to create the plugin.

atlas-create-confluence-plugin

If you want to add a new module to your plugin, you could do this via the command line too. Open your command prompt and browse to the location of your plugin. Within your plugin directory run:

atlas-create-confluence-plugin-module

If you want to run your plugin in its target application, go to the plugin directory using the command prompt and type:

atlas-run

The preceding command will start the application specified in your plugin (Confluence, JIRA, and so on) and automatically install your plugin.

If you are building a plugin that should work for a specific version, or you just want to test your plugin against a new version of the application, you can specify this while starting the application. Run the following commands in your plugin directory:

atlas-clean
atlas-run –-version 5.0.1

The atlas-clean command will clear any previously run version of the plugin. This is only needed if the previous run was a different version.

The SDK bundles the Maven CLI plugin, allowing you to run a command against a development Confluence installation. To use it with your plugin's host application, go to the plugin's project directory (where you created the plugin) and type:

atlas-cli

When the command-line interface is started you can use the command pi to package your plugin and install it into the running Confluence installation.

If you want to quickly test a new version of an application, you can use the standalone command to start that application. You can run this command from anywhere, as there is no plugin required:

atlas-run-standalone-–product confluence --version 5.0.1

There are more commands available, but these are the most used. If you are ever in doubt how a command is used and which are available, run the following command:

atlas-help

When you are building a plugin, you will be using Maven as an underlying library dependency management and build tool. Maven is already bundled with the Atlassian Plugin SDK, so there is no need to install it on your machine. Even if you already have a Maven version installed, you should use the bundled version, as the SDK requires a specific Maven version.

The Atlassian SDK Maven comes with configured settings so that building an Atlassian plugin will be as easy as possible. Using Maven and building your plugin does require an active Internet connection, as Maven will resolve and download all dependencies needed during the build process.

If you are behind a company proxy, make sure to configure Maven accordingly:

With a normal Maven installation, or if you have multiple installations, mvn would be available via your command prompt. To ensure you use the Atlassian provided version, Maven uses atlas-mvn instead.

Every plugin must have a plugin descriptor file. The file, atlassian-plugin.xml, describes your plugin to the target application. The Atlassian SDK generates the atlassian-plugin.xml file when you create your plugin for the first time. The descriptor is also updated when you use atlassian-create-confluence-plugin-module to add a new module.

At some point during the development of you plugin, you will have to update the file manually, so it's a good idea to have a bit of understanding as to what is in the plugin descriptor. The plugin descriptor is located in the directory <plugin_home>/src/main/resources/.

A very minimal plugin descriptor's built looks as follows:

<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}" />
</plugin-info>
</atlassian-plugin>

This descriptor file mostly contains variables; these are Maven variables and will be replaced with the values from your pom.xml file when you build your plugin. The rest of the descriptor file is empty; this plugin does not contain any components, which is very unlikely for a plugin.

We will be adding more modules to this file across this chapter, if you want an overview of the available modules, skip ahead to the Plugin module types section.

When developing your plugin, it is a good idea to use an IDE, short for integrated development environment. A development environment will help you to make fewer mistakes, and can come in very handy when trying to debug your plugin.