Developing for the Atlassian Ecosystem
•
4 gostaram•1,334 visualizações
A presentation delivered to the Auckland Atlassian User Group on the 22nd February, 2012 - where we explore from a high level the Atlassian developer ecosystem, i.e. why you want to develop for it, how to develop for it etc. This covered a number of things which are also landing in Jira 5 and above only i.e. activity streams and remote links. http://www.meetup.com/Akl-AUG/events/47434772/
Recomendados
Recomendados
Mais conteúdo relacionado
Mais procurados
Mais procurados (20)
Destaque
Destaque (6)
Semelhante a Developing for the Atlassian Ecosystem
Semelhante a Developing for the Atlassian Ecosystem (20)
Último
Último (20)
Developing for the Atlassian Ecosystem
- 1. Developing for the Atlassian Ecosystem Alex Henderson Lead Developer, Catch Limited
- 2. Extensibility Options • Extensions – Extending functionality within an Atlassian application – Examples: Misc. Workflow Extensions, Adaptavist create page plugin • Integrations – Integrating with an existing stand-alone product. – Examples: ZenDesk, Enterprise Tester • Applications – Vertical applications hosted within existing Atlassian Products – Examples: Green Hopper, Bonfire, Tempo, Team Calendar
- 3. Why Extend? • Fill an internal need. • Fill an external need. • Over 400 plugins each for Jira and Confluence. • 17,000+ companies using Atlassian Products. • Many plugins are free / open source.
- 4. What is a plugin? • Java JAR file • Contains: – Java classes – XML plugin definition – Resources (CSS, JavaScript, Velocity Templates etc.) • Dependencies • Loaded at startup • Installed/updated via UPM • Can be very big, or very small
- 5. What can a plugin do? • Add new macros to confluence. • Add new dashboard gadgets. • Add new types of custom field. • Add new functions to JQL. • Add new tabs, panels etc. to application UI. • Add new themes to confluence. • And much much more…
- 7. SDK – Overview • Command line tools • Allows you to create a skeleton for a plugin. • Supports all Atlassian products. • For each product provides a set of modules (features) you can generate skeleton code/tests for. • Can allow you to build a single plugin for multiple apps. • Makes it easy
- 8. SDK – Installation • Requires Java JDK to be installed. • Distributed as a zip file – just unzip! • Uses Maven under the hood. • Works on Windows, Linux and Mac. • SDK downloads additional resources as required based on what you are doing.
- 9. SDK – Development Process • Generate a plugin skeleton: atlas-create-APPLICATION-plugin • Generate one or more modules: atlas-create-APPLICATION-plugin-module • Run unit or integration tests: atlas-unit-test / atlas-integration-test • Test in host app: atlas-run / atlas-debug • Package (generate JAR): atlas-package • Release: atlas-release
- 10. SDK - Testing • Unit test stubs generated automatically by SDK. • Can use “RefApp” to test cross-application plugins. • Atlassian SDK snapshots – test against bleeding edge. • Reference / product test data. • Uses JUnit for tests.
- 11. SDK – Stable API • In past, Jira SDK was a moving target. • Plugin compatibility big issue when upgrading for customers. • Stable API in Jira 5.0 resolves the issue. – Stable API in a single jar “jira-api.jar”. – No breaking changes for minor revisions (i.e. API stable for all v5 releases, but may have some breaking changes when going from v5 to v6)
- 12. SDK - Active Objects • Provides a way for your plugin to store data directly in database. • Handles schema management and querying. • Active Objects data integrated into Jira XML backups. • Already being used by: – Green Hopper – Activity Streams plugin • Great for vertical applications.
- 13. SDK – Finishing Touches • Design your plugin to not require restarts: – http://bit.ly/atlas-plugin-reload • Use stable API only if possible • Don’t use deprecated features in API, or deprecated plugins. • Run a checkup on your plugin: – http://checkup.atlassian.com/ • Ensure your application can be localized/internationalized. • Use namespaces/prefixes in JavaScript/CSS.
- 14. Distributing Your Plugin • Plugin Exchange • Licensing/Payment needs to be handled by developer. • Trial license needs to be handled by developer. • If you don’t plan to make your plugin commercial, consider an open source license. • Don’t have to distribute. • Remote API eliminates distribution problems – We will look at this next!
- 15. Remote API • 3rd Party Integration • OnDemand a driving force • More then just remotely creating issues • Inter-product Compatibility • Security Model
- 16. Remote API – RPC Plugin • SOAP API (RPC Plugin) supported in Jira for many years now. • Missing lots of features, compared to REST API. • Officially Deprecated, may be removed entirely in the future. • A number of 3rd party applications have their own modified versions of SOAP API. • Before addition of REST API, customers needed to use “screen scraping” to fill in gaps in API. • Should only be used if you or your customers can’t upgrade to the latest version of Jira.
- 17. Remote API – REST, first looks Fetch issue GET /rest/api/2/issue/TST-1 Update Summary PUT /rest/api/2/issue/TST-1
- 18. Remote API – REST, what can I do? • Custom Fields (including • Voting Search Issues names) • Screen Info • Labels • All Issue Details Rendered as • Attachments HTML • Avatars • Create/Update/Delete Issues • Workflow Transitions • Autocomplete • Icons • Full Metadata • Move • Set Security Levels • Watch • Manage Issue • Search Links/Relationships • Server Info • Change Logs • Project Info • Related & Unresolved Issues • Users Counts per Version • Groups
- 19. Remote API - Activity Streams • Available in Jira 5 and up. • Allows remote applications to publish events that appear within Jira’s activity stream gadget. • New events can be published via REST API using activitystrea.ms protocol. • Will eventually be supported in all Atlassian applications (where applicable). • Activity links can be given additional behavior by developing a full plugin.
- 20. Remote API - Remote Links • Ability to create links from a Jira issue to a remote resource. • API designed to make it easy to create or update with a single request. • Links can have an associated status, or be displayed with a line through them. • A big improvement on previous methods. • Beware: They can be removed by users…
- 21. Open Social Gadgets • Supported in Jira and confluence. • Gadgets can be added to any open social container. • Open social gadgets can be implemented as plugins, or hosted externally. • Implement in many different technologies (Java, Python, PHP, .Net etc.) • Wallboard support.
- 22. Speakeasy • Experimental extension mechanism • Social • Augmentative • Per-user • Writing using simple web technologies. – Html , CSS , JavaScript • REST API’s make much of this possible.
- 23. Development Resources • Atlassian developer home http://developer.atlassian.com/ • Product source code – Only available to license holders – If you don’t have a license, get one, it’s only $10 • Java API docs - http://docs.atlassian.com/ • Atlassian answers - http://answers.atlassian.com/ • IRC – #atlassiandev on http://freenode.net • Stack Overflow – http://stackoverflow.com • Learning Java - http://bit.ly/atlas-learn-java
- 24. Questions ? http://blog.bittercoder.com/ @bittercoder
Notas do Editor
- Hi Welcome to Auckland Atlassian Group.I’m Alex Henderson, Lead Developer here at Catch Limited.We are going to look at the Atlassian ecosystem.My background is as a developer, so I’ve had a little bit to do with developing extensions for the Atlassian platform.Mostly focusing on Jira, because of the Relationship between Jira and Enterprise Tester the product developed by Catch Limited.
- So when we’re talking about developing for the Atlassian ecosystem, what we are talking about is really improving the value proposition of Atlassian productions with new functionality, improving existing functionality, or integrating other technologies into the product.The first thing we can look at is Extensions, extensions are ways in which you can extend existing functionality, or implement features that expand on existing extensions points within an Atlassian production, adding new capabilities. For example – if you take Jira workflows, there are a lot of workflow extensions providing new types of conditions, and many simple confluence macros that allow you to add new types of content to your confluence pages.Integrations on the other hand don’t aim to extend Atlassian productions, but look to integrate an existing 3rd party product with one or more Atlassian products. So a good example of that is Zen Desk, which is a help desk support piece of software, they have a way to integrate Jira so that tickets that are raised on the support desk can be synchronized to issues in Jira. Enterprise Tester is another good example of an Integration, where defects and requirements can be synchronized with issues in Jira.And last of all there are applications, and these are really vertical applications – and you are starting to see more of these, because of the richness of the Jira and Confluence applications, which have introduced features in the last couple of years to support actually building whole applications on those platforms. So we have things like Greenhopper, Tempo, Team Calendars, Bonfire – which are potentially applications would could stand by themselves and still generate value for users – but by hosting them inside an application like Jira or Confluence, the sum of the parts is much more then if the applications were stand-alone, and saves the developer of the plugin for a lot of additional work in building the underlying platform for their product.ExtensionsExtending functionality within an Atlassian applicationExamples: Misc. Workflow Extensions, Adaptavist create page pluginIntegrationsIntegrating with an existing stand-alone product.Examples: ZenDesk, Enterprise TesterApplicationsVertical applications hosted within existing Atlassian ProductsExamples: Green Hopper, Bonfire, Tempo, Team Calendar
- So Why Extend?So generally most plugins start out because you have an internal need – you need a feature, it does not exist, so you build it.And the other reason you build a plugin, is you see an external need – you see a feature/piece of functionality somebody needs, and you decide to fill it.The reasons to do this is the reach of the Atlassian market – Their products have a large and very active user-base, and that make it really easy for customers to find, download and install new plugins via the plugin exchange.
- Java JAR fileContains:Java classesXML plugin definitionResources (CSS, JavaScript, Velocity Templates etc.)Can have dependencies on other pluginsLoaded during application startupCan be installed and updated via UPM (Universal Plugin Manager)Can be very big or very smallCan be an entire application, provide a single extension module or set of extensions (such as misc. workflow extensions plugin)atlassian-plugin.xml<?xml version="1.0" encoding="UTF-8"?><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> <jql-function name="One Hour Ago Jql Function" i18n-name-key="one-hour-ago-jql-function.name" key="one-hour-ago-jql-function" class="com.devdefined.jira.plugins.jira.jql.OneHourAgoJqlFunction"> <description key="one-hour-ago-jql-function.description">Returns one hour before the current date and time</description> <fname>oneHourAgo</fname> <list>false</list> </jql-function> <resource type="i18n" name="i18n" location="atlassian-plugin"/></atlassian-plugin>##Tue Feb 14 17:23:22 NZDT 2012one-hour-ago-jql-function.description=The One Hour Ago Jql Function Pluginone-hour-ago-jql-function.name=One Hour Ago Jql Function
- Add new macros to confluence.Add new dashboard gadgets.Add new types of custom field.(Over the years become less important, in the early days there was a shortage of custom fields for things like multi-level cascade selects)Add new functions to JQL.Obviously the Jira Query Language, or JQL, has lots of extensions – add new calculated fields, add new functions.Add new tabs, panels etc. to application UI.Atlassian have what’s called the AUI, or Atlassian User Interface, which is a plugin/library which allows you to build UI’s in the consistent style used by all Atlassian applications. Also over time they are exposing more and more parts of the various products User Interfaces, so you have places to introduce new functionality – so if you’ve probably used jira 4 or Jira 5 – you problem know many of the view/edit screens have many panels or regions where you can add new content, and of course applications like Greenhopper or Tempo take advantage of the ability to add a top-level tab to the application.Add new themes to confluence.And so much more… The philosophy that Atlassian have taken on board, is to internally develop their own functionality as plugin or as extension points, even if they are not taking advantage of those extension points in their own products.
- So how do you build a plugin – well in the past is quite difficult, but recently has really going quite easy – and that’s using the Atlassian SDK.
- Command line toolsAllows you to create a skeleton for a plugin.Can also generate IDE project files (such as for Eclipse)Supports all Atlassian products.But Jira tends to get SDK features first.For each product provides a set of modules (features) you can generate skeleton code/tests for.Can allow you to build a single plugin that works across multiple Atlassian products.Example: Atlassian feedback plugin – Activity Streams – Gadgets plugin for both Confluence/Jiraatlassian-plugin.xmlMakes it easy to build, install your plugin locally and launch Jira/Confluence/Crowd etc. with a single command.
- Requires Java JDK to be installed (and JAVA_HOME configured)Distributed as a zip file – just unzip.Uses Maven under the hood.Works in Windows, Linux and MacOS. Linux and Mac use shell scripts, windows uses batch files.Uses simple command line scripts i.e. “atlas-run” to launch Jira/Confluence with your plugin.Once SDK installed, depending on the task you executed it will handle downloading additional required resources from atlassian maven repository.Maven has a reputation for “Downloading the internet” – be prepared to have a cup of tea the first time you build a plugin as everything downloads!
- Generate a plugin skeleton: atlas-create-APPLICATION-pluginGenerate one or more modules:atlas-create-APPLICATION-plugin-module (presents a whole set of interactive menus for you)Time to build you build – load it your favourite IDE or text editor, such as Eclipse or Jetbrains IDEARun unit or integration tests: atlas-unit-test / atlas-integration-testTest in host app:atlas-run / atlas-debugPackage (generate JAR): atlas-packageRelease: atlas-release
- Unit test stubs generated automatically for each module.Can use “RefApp” to design and test cross-application plugins.Atlassian SDK snapshots make it possible to build/test your plugin against the bleeding edge of Atlassian development.Reference / product test data can be installed as part of testing the plugin.Uses JUnit for tests.
- So once you start implementing your plugin, you need to then start working with the various features in the Jira or Confluence API to implement your new features.In the past effectively all API features were fair game, but would often change with each point release of Jira or Confluence.This lead to a great deal of pain when it came to build a plugin that worked on multiple versions of Atlassian products, often you were faced with having to upgrade plugins every time a new version of Jira was released – and this also prevented many users from being able to upgrade to the latest version of Jira until the slowest plugin developer finally updated their plugin for the new version of Jira.Now this has been addressed in the Jira 5 release with what’s called the stable API – and though it’s yet to really be seen, I believe this is going to greatly reduce the amount of work a Developer needs to do to make their plugin compatible with future versions of Jira as they are released.Deprecation/discourage use of features.
- So if you are building a simple plugin, so say your building a plugin for Jira, and it’s working with issues, often the issue provides the place where the information can be stored.Insulates you from having to manage your schema and schema migrations, changes over time.Also makes it easy to write a query that will work across all the database types supported by Jira/Confluence.Active Objects work nicely with everything else, including XML backups/restores.Already being used by applications such as Green Hopper, as well as the Activity Streams plugin.Takes care of ensuring plugins which have objects with the same names, don’t end up with conflicting table names.-----But if you are building a vertical application Provides a way for your plugin to store data directly in database.Handles schema management and provides SQL support (while taking care of cross-database issues).Active Objects data integrated into Jira XML backup/restore process.Already being used by Green Hopper and Activity Streams plugin.Well suited to people building vertical applications within an Atlassian application.
- It’s been proven that people having to restart Jira/Confluence due to installing or upgrading a plugin can severely hamper adoption of your plugin.There are non-stable API’s within Jira, and obviously Jira itself does use those API’s, but you should try to avoid it, to make your plugin more maintainable over time.Deprecated features / plugins – avoid these if at all possible, and once you know something’s deprecated, move away from it as quickly as possible.When implementing your application, its easy to fall into the habit of using hard-code strings in your UI, but if you ensure your application supports i18n right from the start, this doesn’t add a lot of work, and means you can easily add support for other languages.Plugincheckup - validate a plugin against a wide array of Atlassian products/versions. The checkup will check your plugin for usage of product APIs that are either not available, deprecated, or private.Design your plugin so it can be installed/upgraded without an App restart.More details here: http://bit.ly/atlas-plugin-reloadUse stable API only if possibleDon’t use deprecated features in API, or deprecated plugins where possible (such as SOAP API)Ensure your application can be localized/internationalized (don’t hard code UI strings).Use namespaces/prefixes in JavaScript/CSS – to avoid conflicts with other plugins.
- Plugin Exchange (soon to be marketplace)Plugin Exchange – you can signup, then create a vendor for your plugin, then add one or more plugins to your profile – at which point your plugin will be submitted to Atlassian, and approved in 2 or 3 days.As part of this process your plugin will be verified to not have a plugin key that conflicts with existing plugins (shouldn’t happen if you use the naming convention suggested by Atlassian, unless someone else in your organisation has alread created a plugin with the same name).Licensing/Payment needs to be handled by developer.Trial license needs to be handled by developer.If you don’t plan to make your plugin commercial, consider an open source license.Using Remote API is a nice way to avoid distribution issues.You Don’t have to distribute your plugin via the Atlassian plugin exchange – if it’s a confluence macro you developed for use by your organisation only, for example, or if you have build an open source plugin and wan’t people to download and build it themselves, rather then you packaging it up and making it available (And then having to support it) then distribution via the plugin exchange (Marketplace) may not be for you!
- 3rd Party IntegrationIntegrate 3rd party products with Atlassian tools, without a plugin.OnDemand a driving forceAtlassian On-demand only comes with a small subset of “Approved” plugins – Remote API’s allow you to work around this.More then just remotely creating issuesAs of Jira 5, new API’s are being introduced which can provide integration that was previously only possible via plugins.Shared CapabilitySome of the Remote API’s are shared amongst multiple Atlassian products – support multiple Atlassian apps at once.Security ModelAPI does not let you perform actions which can not be performed via the User Interface in some way (you can’t circumvent user-level security model).
- SOAP API (RPC Plugin) supported in Jira for many years now.Missing lots of features, compared to REST API.Officially Deprecated, may be removed entirely in the future.but not likely to happen before Jira 6, or at least Jira 5 adoption up-swing (no official indication yet..)A number of 3rd party applications have their own modified versions of SOAP API.Mostly to address shortcomings/bugs.Before addition of REST API, customers needed to use “screen scraping” to fill in gaps in API.This got quite tricky with the introduction of WebSudo in Jira 4Should only be used if you or your customers can’t upgrade to the latest version of Jira.And even then, cost of development vs. upgrade often makes this is a poor choice.
- Available in Jira 5 and up.Allows remote applications to publish events that appear within Jira’s activity stream gadget.New events can be published via REST API using activitystrea.ms protocol.Will eventually be supported in all Atlassian applications (where applicable).Activity links can be given additional behavior by developing a full plugin.
- Ability to create links from a Jira issue to a remote resource.API designed to make it easy to create or update remote links with a single operation.Links can have an associated status, or be displayed with a line through them (to show they are closed/complete/cancelled).A big improvement on trackback links or links in comments.Links can only be added via API, but may be removed by users.
- Jira and confluence support open social gadgets.Open social gadgets can be added to any open social container – allowing gadgets from one product to be added to a dashboard/page in another.Open social gadgets can be implemented as plugins, or hosted externally.You can implement an open social gadget in many different technologies such as Java, Python, PHP, .Net etc.Wallboard support – via wallboard view-type extension to the gadget spec.
- Compatible with Jira 4.3 and up.Compatible with Confluence 4.0 and up.Comes with a mini web based IDE.Extensions in speak-easy are per user.Great way to get into extending Jira or Confluence, or prototyping plugins.Augmentative = Plugins augment functionality in Jira/Confluence, but turning them off should never break confluence or Jira (so much less upgrade pain).
- Atlassian developer home http://developer.atlassian.com/Product source codeOnly available to license holdersIf you don’t have a license, get one, it’s only $10Java API docs - http://docs.atlassian.com/Atlassian answers - http://answers.atlassian.com/IRC – #atlassiandev on http://freenode.netStack Overflow – http://stackoverflow.comLearning Java - http://bit.ly/atlas-learn-java