Writing your first plugin FAQ
Build Failure - Manifest Validation Errors
If you use a vendor name of "Atlassian" in your
atlassian-plugin.xml file, you may receive errors like this:
The vendor should be set to something other than "Atlassian", since we have a number of additional validations triggered by that vendor string. For example:
To skip the manifest validation, you can add the following tag to the configuration element in your pom.xml
Note: This is not recommended if you want to make your plugin available to multiple Atlassian applications.
Cannot Log In to Confluence using Admin Account
If you find that you cannot log in to your test Confluence instance using the admin account, set your plugin to build against Confluence 2.6.1 or later using the
Choosing a Logging Framework
Three logging frameworks are available to plugins:
- Log4j 1.2.15
- Commons Logging 1.1.1
- SLF4J 1.5
We recommend Simple Logging Facade for Java (SLF4J) as a the primary logging framework.
You should ensure that none of these libraries are bundled with your plugin (in
META-INF/lib) as this will prevent the host application from logging any of your plugin's log messages.
You can check your plugin's dependencies by using
mvn dependency:tree and then exclude any transitive dependencies in the
Choosing a Package Name
com.atlassian.confluence.plugins.*. That is confusing to people who try to use the plugin. Use a real package name that corresponds to your organisation or project. For example:
org.mycompany.confluence.plugins.*. The Sun Java documentation has some tips about conventions used to ensure unique package names.
Eclipse Maven Plugin Build Error
Please note that the new Eclipse plugin is unable to deal with source 'includes' and 'excludes'.
Use the following command :
mvn org.apache.maven.plugins:maven-eclipse-plugin:2.6:eclipse as this will force mvn to use version 2.6 of the maven eclipse plugin.
The error that you will see if 2.7 is used in your mvn build :
If you change pom.xml, you may need to restart the atlas-cli
If you are using
pi for a fast development cycle of your plugin and you get compilation errors about "Unable to run mojo" and no Java line number in your plugin source code, it may be that you changed the dependencies in
pom.xml but didn't restart
Instant Loading of Plugin Resources
To enable this feature, set the system property
plugin.resource.directories to a comma-delimited list of directories containing plugin resources. For example, to point the framework at your current project's resource directory when running an Atlassian application from Maven, you could set the
Overriding the application's webapp when developing your plugin
The Atlassian Plugin SDK makes it easy to override any component of the application's webapp.
- Create a
***is the name of the application you're developing your plugin against. For example
- To this directory add the resources you want to add (or override) following the webapp directory structure.
Now when you run your application via
atlas-integration-test, it will use the updated WAR built from the application configured in your
pom.xml and the added resources you have defined.
This can be useful for example to disable the velocity caches by overriding
velocity.properties when developing a Confluence plugin.
src/test/resources/confluence-app/WEB-INF/classes/velocity.properties file specifying the properties as defined in the Confluence developer documentation. That's it.
Specifying a particular version of the host application
atlas-run command will download the latest version of the application binaries into your local Maven repository. If you want to develop against a version of the host application other than the very latest, you can specify the version to use as a parameter of your
For example, let's assume you want to use Confluence 3.1:
atlas-run -v 3.1
atlas-run --version 3.1.
Alternatively, you can permanently change the application version number in the dependencies section of your POM. Note that your POM may use a property to hold the version number, like this:
You plugin will always build and deploy against this version, until you change this property.
For example, if you are happy to use Confluence 3.1 for a while, you would change the version to the following:
Tips for Functional Tests with Selenium
Add atlassian-selenium-browsers-auto to your pom.xml
Add this XML to the
<dependencies> section in your pom.xml:
You should verify the
<version> value is the latest by searching for the
<groupId> in Atlassian's Maven repository.
Write a Selenium test
The Atlassian Plugin SDK comes with support for integration/functional tests that will run with the target Atlassian application started and your plugin installed. You just have to create one or more tests in the
src/test/java/it directory. The convention is if your code is in the
com.mycompany.myplugin package, your integration tests would be in the
it.com.mycompany.myplugin package or
To use Selenium in these tests, the
atlassian-selenium-browsers-auto artifact provides a few static helper methods. These methods, when used for the first time:
- Detect your operating system
- Install the appropriate browser (FireFox 3.5 is the default) for your OS in
- If Linux and
xfvb.enableis set to true, start
Xvfbon an open DISPLAY detected automatically
- Start the Selenium server
- Start the newly installed browser
This all happens in the background, so you should just be able to focus on your test.
Here is a simple test that hits the home page and looks for the text of "Hello world":
Specify a Browser
If you want to specify a browser other than Firefox 3.5, you can do so by specifying the
selenium.browser system property in your atlassian-<product>-plugin configuration. For example:
You can find out what strings are valid by looking at the
Using the Atlassian Plugin SDK with a Source Code License
This page is relevant to developers who hold a commercial license for an Atlassian application, with access to the source code.
Since you have purchased a commercial license to an Atlassian application, such as Confluence, you have access to the application source code. You can download a source distribution by visiting http://my.atlassian.com. Then you can attach the application source code to your plugin project, so that you can step through the application code in your debugger. It is often helpful to do this to better understand the API or to track down problems.
Once you have downloaded and unpacked the source distribution, you will see a number of directories and files, exactly as they are checked out of our SVN repository. This is perfect for reading and exploring, but it does not do you much good in the brave new world of Maven 2. You'll need to create and install source artifacts into your local Maven repository. Once you have done that, the Maven IDE plugins will recognise that they are there and link them up for debugging purposes.
From the top level of the source distribution, run:
atlas-mvn source:jar install -Dmaven.test.skip=true -DskipTests=true
This will build JAR files containing most of our source code into the
target directory of each subproject. The important items are now set up, including the core application source code.
You can copy the JAR files into your local Maven repository to make them available in your IDE. For example, to install the source code for Confluence 3.4 core, copy
$HOME/.m2/repository/com/atlassian/confluence/confluence/2.10. After doing so, run
atlas-mvn idea:idea or
atlas-mvn eclipse:eclipse again, close and reopen the project; the sources should now be available.
A Note about Memory
This is a resource intensive process, and you may need to allocate more memory to Maven in order to complete it. You can do so by setting an environment variable called
MAVEN_OPTS, like this:
A Note about Versions
Make sure that you download and install the same version of the source code that is set in the
atlassian.product.version property in your
Using your own log4j configuration for your plugin
The Atlassian Plugin SDK makes it easy to override the application's
log4j.properties file, so that you can do custom logging for your plugin.
- Create your
log4j.propertiesfile. A simple way to do this is to copy the application's
log4j.propertiesfile and change it to suit your needs.
- Place the
log4j.propertiesfile somewhere in your source tree, for example in
src/aps/log4j.properties('aps' means the Atlassian Plugin SDK).
Now you can run your application via