Tutorials and guides

Our tutorials and guides are split into topics to help you learn to build apps using the Atlassian SDK. Tutorials provide step-by-step instructions for working through an example, while guides explore information about a particular topic in depth.

If you’re getting started with developing on Atlassian products, we recommend working through some tutorials. You can also check out the Product-specific tutorials page for more information about using the Atlassian SDK to build apps for specific products.

Note, these resources are relevant for Data Center products only. If you're using a cloud product, check out our cloud documentation instead.

Setup

The resources in this section will help you get set up to develop on our Data Center products. This includes learning about the Atlassian SDK, setting up your IDE, and creating an app.

Tutorials

• Install the Atlassian SDK on a Linux or Mac system
• Install the Atlassian SDK on a Windows system
• Set up the Atlassian Plugin SDK and build a project
• Create a HelloWorld plugin project
• Create a plugin skeleton
• Configuration of Instructions in Atlassian Plugins

Guides

• About the platform
• About AMPS build options
• AMPS build configuration reference
• Atlassian Platform common components
• Command reference
• Configure IDEA to use the SDK
• Configure NetBeans to use the SDK
• Creating a plugin skeleton with the Atlassian SDK
• Working in an IDE

Development tips

Learn about best practices, common development tasks, and tooling.

Tutorials

• Explore the installed SDK and the atlas commands
• How to quickly switch between Java 11, Java 8 and OpenJDK versions
• Learn the development platform by example
• Modify the plugin
• Modify the plugin using QuickReload
• Run your plugin in the container

Guides

• About the Atlassian RefApp
• Additional developer resources
• Automatic plugin reinstallation with FastDev
• Automatic plugin reinstallation with QuickReload
• Behind the scenes in the plugin framework
• Best Practices
• Changing the default Maven version
• Common coding tasks
• Configure AMPS to run Jira Core with additional applications installed
• Configuring your project
• Creating a remote debug target
• Developer tools
• Development cycle
• Documenting your APIs with the Atlassian REST API Browser
• Enabling SQL logging
• Example extensions
• Finding your plugin in the host application
• Frequently used commands
• Getting help with the SDK
• Plugin framework
• Start a host application with a plugin installed
• Working with JiraThreadLocalUtils
• Working with Maven
• Working with the POM
• Working with the SDK
• Using the REST API Browser

Storage

The resources in this section help you with how to persist data in your apps. This includes learning about Active Objects, best practices, and working with entities.

Tutorials

• Getting started with Active Objects
• Installing Active Objects
• Store and retrieve plugin data

Guides

• Active Objects
• Active Objects FAQ
• Active Objects plugin module
• Best practices for developing with Active Objects
• Column names
• Creating an EntityManager
• Creating entities
• Declaring JNDI datasources in AMPS
• Deleting entities
• Developing your plugin with Active Objects
• Finding entities
• Getting entities by PK
• Handling AO upgrade tasks
• ManyToMany relationship
• OneToMany relationship
• OneToOne relationship
• Storing plugin settings
• Table names
• The Active Objects library
• Upgrading your plugin and handling data model updates

Upgrading Active Objects

Use these guides to upgrade your version of Active Objects when required.

• AO 0.18.x upgrade guide
• AO 0.29.x upgrade guide
• AO 1.0.0 upgrade guide
• AO 1.1.0 upgrade guide
• AO 1.2.0 upgrade guide
• How to upgrade AO to 0.18.x in Jira 5

Testing

Learn about how to set up testing for your app. This includes integration tests, unit tests, and testing persistence.

Tutorials

• Create and run traditional integration tests
• Create and run unit tests
• Create test data and a test fixture
• Generate and Examine skeleton tests
• Run Wired Tests with the Plugin Test Console

Guides

• Testing
• Testing a plugin that uses Active Objects

Wiring

These resources explore how some of the internal wiring of your app works. This includes Spring, OSGi, and managing dependencies.

Tutorials

• Exposing host components via Spring

Guides

• Adding the maven dependency
• Advanced configuration with Spring XML files
• Automatic generation of Spring configuration
• Going from Plugin to OSGi bundle
• Managing dependencies
• OSGi, Spring and the Plugin framework
• Using the OSGi Browser
• Lifecycle of a bundle
• Setting the platform version dependency in the POM
• Declaring components using Spring Java configuration

Client-side

Use these resources to understand how to work with the client-side code in your app. This includes using the Atlassian UI components (AUI), using data providers, and minification.

Note, this includes information on Speakeasy, which is no longer supported. Speakeasy is an experimental framework for creating front-end only apps, but is not compatible with recently-released versions of Confluence.

Tutorials

• Create a GUI with templates and AUI

Guides

• Adding a configuration UI for your plugin
• Adding data providers to your plugin
• Atlassian Template Renderer
• Developing Speakeasy extensions
• Extending the Speakeasy plugin
• Installing Speakeasy
• Speakeasy
• Supporting minification of JavaScript and CSS resources
• Troubleshooting Speakeasy

REST

The resources below cover how to develop REST APIs in your app.

Tutorials

• Developing a REST service plugin

Guides

• Atlassian REST API design guidelines version 1
• REST API development

Other

This section lists tutorials and guides that are not related to major components of the Atlassian SDK, such as working with activity streams, internationalization, and releasing apps.

Tutorials

• Control access with SAL
• Convert component to servlet module
• Quick start guide to embedding
• Scheduling events via SAL tutorial
• Set up event-driven messaging with Atlassian Event

Guides

• Activity streams
• Adding activities to a third-party feed with the REST API
• Adding activities to a third-party feed with the Java API
• Adding WebSudo support to your plugin
• Application links
• Checking Plugins for API Compatibility
• Configuring the plugin
• Configuring the Velocity allowlist
• Configuring the Velocity file allowlist
• Consuming an activity streams feed
• Converting from version 1 to version 2 (OSGi) Plugins
• Creating an admin configuration form
• Creating plugin module instances
• Early access programs (EAPs)
• Embedding the Plugin Framework
• Internationalising your plugin
• Packaging and releasing your plugin
• Plugin release checklist
• Pluralising internationalisation strings
• Stateless web-resource transforms and conditions
• Using standard page decorators