![Open(-ish)
Source
[2001]](https://image.slidesharecdn.com/pluginarchitecture-150326200935-conversion-gate01/85/Rewriting-a-Plugin-Architecture-3-Times-to-Harness-the-API-Economy-18-320.jpg)
!["name": "Hello World", "description": "…",
"key": "com.example.myaddon", "apiVersion": 1,
"baseUrl": "http://example.com/myaddon",
"modules": {
"generalPages": [{
"name": { "value": "Greeting" }, "key": "hello-world",
"location": "system.top.navigation.bar",
"url": "/helloworld.html"
}]
},
"scopes": [ "read", "write" ],
"authentication": { "type": "jwt" },
"lifecycle": { "installed": "/add-on-installed-callback" }
where it is hosted
which modules it uses
which scopes it needs
recognize the user](https://image.slidesharecdn.com/pluginarchitecture-150326200935-conversion-gate01/85/Rewriting-a-Plugin-Architecture-3-Times-to-Harness-the-API-Economy-98-320.jpg)
![Example JIRA WebHooks
• HTTP callback to a URL
• Filtered by JQL
• When specific event occurs
"modules": {
"webhooks": [{
"event": "jira:issue_created",
"url": "/issue-created"
}]
}](https://image.slidesharecdn.com/pluginarchitecture-150326200935-conversion-gate01/85/Rewriting-a-Plugin-Architecture-3-Times-to-Harness-the-API-Economy-102-320.jpg)
Rewriting a Plugin Architecture 3 Times to Harness the API Economy
- 2. Rewriting a Plugin Architecture 3 Times to Harness the API Economy
- 3. A couple of Atlassians who are passionate about plugins Tim Pettersen Developer Provocateur @kannonboy Ian Buchanan Developer Partisan @devpartisan
- 4. API Economy
- 5. Economy
- 6. $50,000,000 *Paid to ISVs to date.
- 8. $1,000,000,000 *Paid to ISVs in 2013. http://www.partner-path.com/2013/12/salesforce-partner-ecosystem/
- 10. API Economy SPI
- 13. P2 (2008)
- 19. Why it’s awesome! Customers can “scratch their own itch” Atlassian devs can focus on the 90% Customization == stickier product Devs who customize, evangelize
- 20. Why it sucks.. Developer support load Poor plugin UX == poor product perception Pain to build the entire product Massive barrier to upgrade
- 22. JIRA 3.0
- 23. How? Wherever there is a collection of type FOO, let the end user inject their own implementations of FOO.
- 24. “Web fragments”
- 25. <ul> </ul> <li><a href=“/dashboard.jspa”>Home</a></li> <li><a href=“/project.jspa”>Browse Project</a></li> <!-- … --> <li><a href=“/admin.jspa”>Administration</a></li>
- 26. interface WebItem { String getHref(); String getText(); } class FooWebLink implements WebItem { } public String getHref() { return “http://foo.com”; } public String getText() { return “Foo”; }
- 28. <li><a href=“/dashboard.jspa”>Home</a></li> <li><a href=“/project.jspa”>Browse Project</a></li> <!-- … --> <li><a href=“/admin.jspa”>Administration</a></li> <ul> </ul> <% for (WebItem wi : pluginAccessor.getModules()) { %> <li> <a href=“<% wi.getHref() %>”> <% wi.getText() %> </a> </li> <% } %>
- 29. Plugins promote abstraction and enforce modular architecture!
- 30. Two plugins looks great! 3+ plugins.. not so hot.
- 31. Every (pluggable) collection is now potentially infinitely large.
- 33. public void transitionIssue(Issue issue, Transition tn) { // update issue state // .. // send email to watchers for (User watcher : issue.getWatchers()) { issue.emailTo(watcher); } }
- 34. public void transitionIssue(Issue issue, Transition tn) { // update issue state // .. } public static interface PostFn { void onTransition(Issue issue); } public class EmailFn implements PostFn { public void onTransition(issue) { for (User watcher : issue.getWatchers()) { issue.emailTo(watcher); } } }
- 35. public void transitionIssue(Issue issue, Transition tn) { // update issue state // .. // trigger post functions for (PostFn fn : pluginAccessor.get(PostFn.class)) { fn.onTransition(issue); } } public class EmailFn implements PostFn { public void onTransition(issue) { for (User watcher : issue.getWatchers()) { issue.emailTo(watcher); } } }
- 36. Adding a new “plugin point” is easy if you already have good abstraction!
- 37. You SHOULD make “pluginizing” a feature as simple & quick as possible. Otherwise if there’s a crunch for time, it won’t happen. Spike it Make it work Test it Add an API / SPI Ship it
- 38. for (PostFn fn : pluginAccessor.get(PostFn.class)) { fn.onTransition(issue); } ArithmeticException StackOverflowError while (true) {} OutOfMemoryError ClassNotFoundException ClassCastException
- 39. Murphy’s law: If a plugin can fail, it will. Horrifically.
- 40. for (PostFn fn : pluginAccessor.get(PostFn.class)) { fn.onTransition(issue); } Code defensively try { } catch (Exception e) { log.error(“Plugin post-function failed”, e); } log.debug(“Invoking ” + fn);
- 41. Corollary: If an API is public, it will be used. Often incorrectly.
- 42. public void publicApiMethod(List<?> list) .. } Show them the way if (list == null) throw new NullPointerException( “list must not be null” ); if (list.isEmpty()) throw new IllegalArgumentException( “list must not be empty” ) ); /** * @param list a non-null, non-empty list */
- 43. Backend • Custom fields • JQL functions • Workflows (post-functions, conditions) generic • Servlets • Filters • Event listeners
- 44. https://bitbucket.org/atlassian/atlassian-plugins Source (BSD 3-clause licensed) Embedding Guide http://bit.ly/embedding-plugins Atlassian Plugins
- 45. • Host application exposes some “plugin point” interfaces public static interface PostFn { void onTransition(Issue issue); } • Plugin developer provides concrete implementations public class EmailFn implements PostFn { // send email to watchers for (User watcher : issue.getWatchers()) { issue.emailTo(watcher); } } How it works (1 of 3)
- 46. • Plugin developer adds an XML descriptor (remember it’s 2004) <post-function class=“com.foo.EmailFn” weight=“10” /> • Developer packages up the class and XML in a JAR and puts it on the classpath atlassian-jira/WEB-INF/lib/my-cool-plugin-1.0.jar/ How it works (2 of 3) atlassian-plugin.xml com/foo/EmailFn.class
- 47. • On startup, plugin system parses the XML and instantiates classes with Spring DI • The PluginAccessor is injected into other components and used to look up modules. • Because the class path is static, the PluginAccessor caches plugins very aggressively. How it works (3 of 3)
- 49. Why it’s awesome! Easier customization by end-users Smoother upgrades Improved customization UX Architectural benefits Simple to implement
- 50. Why it sucks.. Totally bespoke, non-standard Need to restart to install plugins No API delineation Shared classpath
- 51. Re-architecting as plugins a bunch of work
- 52. Dogfooding APIs?
- 53. product manager
- 54. “PM friendly” benefits! Release plugins out of band Ship “dark features” Customers can turn stuff off Release paid plugins ($$$) Architecture == velocity
- 55. Make sure your plugin system works. Nothing turns off a plugin developer like a broken API or an unstable platform.
- 56. P2 (2008)
- 57. P2 (2008)
- 58. Why plugins suck.. Totally bespoke, non-standard Need to restart to install plugins No API delineation Shared classpath
- 59. OSGi
- 62. Why it sucks.. Totally bespoke, non-standard Need to restart to install plugins No API delineation Shared classpath
- 63. Why it sucks.. OSGi is pretty complicated
- 64. 175Kb of text JIRA Agile’s MANIFEST.MF
- 65. P1 P2 <post-function class=“com.foo.EmailFn” weight=“10” /> public class EmailFn implements PostFn {..} + = a working plugin <post-function class=“com.foo.EmailFn” weight=“10” /> public class EmailFn implements PostFn {..} Import-Package: com.atlassian.jira;version=“5.0”, Export-Package: org.apache;version=“3.3” <component> .. </component> + + + = a working plugin … maybe
- 66. Abstracting OSGi and a few other things..( )
- 67. C nsPr s • Less upgrade pain • Easy onboarding for new users • Startup time • Leaky abstraction • Non-standard use of standard tech • Proxies all the way down • Complexities
- 69. Supporting your ecosystem Photo: Nicholas A. Tonelli
- 71. Good for devs! Paint-by-numbers marketing Pricing & licensing APIs Feedback Tracking & analytics
- 72. Good for customers! Central authority for add-ons Less fragmented UX Ratings & reviews Unified billing
- 73. Focus shifts from user to vendor customization
- 74. Building a marketplace is non-trivial
- 76. Tim’s top tip for dev docs Keep your documentation as close to the code as possible.
- 77. Bind the code..
- 78. ..to the docs!
- 80. Code talks! Make sure you have a simple process for open sourcing and liberally licensing example add-ons.
- 81. Meta-Developer Tools Photo: Biser Todorov
- 82. SDK Fully automate plugin ALM Spin up products in “developer mode” Tight development loop Provide realistic test data Dogfood it! FREE
- 83. /stash/projects
- 86. /stash/projects
- 89. Developer Mode Trim out dev speed killers (websudo, etc) Expose logs & debug info Release your own internal productivity tools Add in custom “dev mode” plugins
- 90. (2014)
- 91. What is Atlassian Connect? Remote Plugins REST API • Drive the product via its REST API WebHooks • Receive notifications from the product via WebHooks • Inject content into the product UI via iframes UI Atlassian Product Plugin Service Add-ons
- 92. Why? Atlassian Cloud (SaaS) Run 3rd party code out-of-process Improved customization UX (yet again) Architectural benefits
- 94. • Connect is a new layer on top of the older plugin model. • Same Marketplace serves up Connect plugins. • Same plugins still available in the Marketplace. • Same REST APIs still available for both Server and Cloud. • Connect adds a new mode of integration. Building up http://housebeauty.net/dressy-modern-townhouse-design-with-rooftop-garden-and-glass-walls/eye-catching-green- roofed-penthouse-apartment-rooftop-garden-with-deck-surrounded-by-glass-balustrades/#image-1
- 95. How? Wherever a module is called, let a third-party inject a new feature. remember web fragments
- 97. • Declare plugin with a descriptor. • Extend the Atlassian application UI with modules. • Request appropriate scopes. • Recognize the user. • Call the Atlassian application's REST API. • Respond to the Atlassian application's webhooks. • Register on the Atlassian Marketplace. • Respect plugin licensing. How to author a Connect Plugin
- 98. "name": "Hello World", "description": "…", "key": "com.example.myaddon", "apiVersion": 1, "baseUrl": "http://example.com/myaddon", "modules": { "generalPages": [{ "name": { "value": "Greeting" }, "key": "hello-world", "location": "system.top.navigation.bar", "url": "/helloworld.html" }] }, "scopes": [ "read", "write" ], "authentication": { "type": "jwt" }, "lifecycle": { "installed": "/add-on-installed-callback" } where it is hosted which modules it uses which scopes it needs recognize the user
- 99. Example Scopes for JIRA PROJECT_ADMIN DELETEWRITE ADMIN READ
- 100. GET /myaddon?jwt=<jwt-token> http/1.1 POST /jira/rest/api/2/issue/AC-1/attachments http/1.1 Authorization: JWT <jwt-token> Recognizing the user with JWT
- 101. Example REST API for Confluence • URLs for resources • HTTP verbs • Parmeters filter collections • JSON data • HAL(ish) links (newer APIs)
- 102. Example JIRA WebHooks • HTTP callback to a URL • Filtered by JQL • When specific event occurs "modules": { "webhooks": [{ "event": "jira:issue_created", "url": "/issue-created" }] }
- 103. Register on the Atlassian Marketplace • Find: in context catalog of add-ons • Try: manage leads • Buy: manage sales and licensing
- 104. • Vagrant Box for local development • JSON descriptor validator • JWT decoder • Marketplace wizard to create a Connect listing • Access Token model for private plugins • Webhook Inspector Developer Tools for Atlassian Connect
- 105. C nsPr s • Code in any language • Use any build & dev tools • Use anything: databases, search indexes, caching services, etc • Host and scale a service • No automated devloop (P2 SDK) • Provide everything: databases, search indexes, caching services, etc
- 106. Why it’s awesome! BYOS (Bring your own stack) More services, than products Sandboxing UI Design Aligned with microservice thinking
- 107. Why it sucks.. Complex to troubleshoot Harder to create concrete examples More developer tools, not just docs More interfaces must be stable
- 108. Remember SPIs?
- 110. What’s Next? Consolidate and expand Vendor add-on • Extend Bitbucket and HipChat • Build complex vertical apps: powered by Atlassian • Build integrations between Atlassian applications Atlassian add-on
- 111. Questions?
- 112. A couple of Atlassians who are passionate about plugins Tim Pettersen Developer Provocateur @kannonboy Ian Buchanan Developer Partisan @devpartisan