This AtlasCamp, we're talking a lot about Atlassian Connect and the new Confluence REST API. This session will bring it all together with an overview on building a Connect add-on with Confluence. We will cover best practices when writing complex dynamic macros with respect to security, performance and maintainability.

1. June 3-5, 2014 | Berlin, Germany

2. @matthewjensen
Matthew Jensen, Confluence Ecosystem, Atlassian
Writing Connect Add-ons
for Confluence

3. • About Me:!
• Almost 7.5 years at Atlassian
Introduction
81%
19%

4. • About Me:!
• Almost 7.5 years at Atlassian!
• Over four years on Confluence
development
Introduction
81%
9%
10%

5. Why is it so hard to write a Confluence
plugin?
— Matthew Jensen, Confluence Ecosystem
”
“

6. Confluence Ecosystem

7. Confluence Platform
Spaces
Questions
?
??
?
?
?

8. Connect
and
Confluence

9. SAME
BUT DIFFERENT
SAME

10. Confluence Connect
DESIGN
SECURITY
PERFORMANCE
MACROS

11. HiliteMe
MACROS

12. Example
Consider a macro to pretty print your code
MACROS

13. Example
MACROS
This macro can make any code look great!

14. Example
http://bitbucket.org/mjensen/hilite-me-addon
MACROS

16. • Can be of any size!
• Can contain sensitive information
Macro Body
CONFIDENTIAL
MACROS

17. • Only use HTTP GET operations!
• Flexibility!
• This concern is new with Connect
Macro Bodies
MACROS

18. VSDynamic
Macros
Static
Macros

19. Dynamic Content Macros
Confluence Add onBrowser
Request
HTML
IFrame
Unformatted Code
Formatted
Requested
Returned
Macro Loaded
MACROS

20. • Dynamic Content Macros are good:!
• when they can take a while to load!
• when it involves a third-party integration!
• requires authentication to collect the body!
• when your macro is block macro
Dynamic Content Macros
MACROS

21. Static Content Macros
Confluence Add onBrowser
Request
Unformatted Code
Formatted
Code
Requested
Returned
MACROS

22. • Static Content Macros are good:!
• when you have many on the page!
• when the body is small or not sensitive!
• when you can avoid authentication
Static Content Macros
MACROS

23. • The Code Format Macro is a Dynamic Content Macro:!
• the body can be of any size!
• it integrates with a third party!
• its hard to predict the render time or the size of the output
Code Format Macro
MACROS

24. Confluence Connect
DESIGN
SECURITY
PERFORMANCE
MACROS

25. Example
• Consider a simple connect macro to include a status indicator
on your page!
• Status as a parameter, and no body.
PERFORMANCE

26. Example
PERFORMANCE
http://bitbucket.org/mjensen/status-addon

27. Static Content Macros
Confluence Add onBrowser
status=Awesome
Awesome
Requested
Returned
PERFORMANCE
Cached

28. • Design allows for aggressive cache settings!
• You should set appropriate cache headers for your all your
resources
Caching
res.setHeader(!
!! ! 'Cache-Control',!
!! ! ['private','max-age=3600']!
);
routes/index.js
PERFORMANCE

30. • A versioned URL allows you to control when your cached
content is refreshed
Versioned URLs
app.get('/v1/my-macro',!
function (req, res) { … }!
)
routes/index.js
PERFORMANCE

32. • The macro body can be passed as a parameter!
• This can allow you to use caching on your resources, even
when the body is needed
Body as a Parameter
"staticContentMacros": [{!
"url": "/macro?body={macro.body}", !
…!
}]
atlassian-connect.json
PERFORMANCE

33. Body as a Parameter
Confluence Add onBrowser
Rendered
Requested
Returned
body=Awesome
PERFORMANCE
Cached

34. • Body is limited to 128 characters!
• May appear in Confluence logs!
• May be tracked in caches or proxies
Body as a Parameter
PERFORMANCE

36. • Some integrations happen synchronously!
• Remote Conditions and Static Content Macros
Synchronous Callbacks
Confluence Add onBrowser
Request
Slow Response
!#$
PERFORMANCE

37. Confluence Connect
DESIGN
SECURITY
PERFORMANCE
MACROS

38. Do you need to store any data at all?
Data Storage
SECURITY

40. Web Security
Vulnerable area
Permitted to user Permitted to add on
SECURITY
READADMIN

41. • Use JWT for simple integration with Confluence REST api!
• Define your scopes to be as restrictive as possible
Web Security
{!
"key": "my-addon",!
"scopes": [ "read" ],!
"authentication": { "type": "jwt" },!
…!
} atlassian-connect.json
SECURITY

42. Confluence Connect
DESIGN
SECURITY
PERFORMANCE
MACROS

43. • Static add ons contain only html and javascript files
Static Add Ons
Confluence Add onBrowser
DESIGN

44. Coming Up

45. Blueprints
COMING UP

46. Blueprints
"blueprints": [{!
"key": "hello-world-blueprint",!
"name": { "value": "Hello World Blueprint" },!
"template": {!
"url": “/blueprints/hello-world.xml”!
},!
"icon": { "url": "/blueprints/hello-world.png" }!
}]
atlassian-connect.json
COMING UP

47. Blueprints
<table><tbody>!
<tr><th>Name</th><th>Date</th></tr>!
<tr>!
<td>!
<ac:placeholder>Enter today's date here</ac:placeholder>!
</td>!
<td>!
<at:var at:name="user"/>!
</td>!
</tr>!
</tbody></table>
atlassian-connect.json
COMING UP

48. Blueprints
COMING UP

49. Blueprints
COMING UP

50. Blueprints
https://bitbucket.org/mjensen/hello-blueprint-connect
https://ecosystem.atlassian.net/browse/AC-1082
Example Plugin
Blueprints Ongoing Work
Help us set the direction!
COMING UP

51. CQL
COMING UP

52. We need you!
Yes you!
COMING UP

53. Questions?
@matthewjensen
mjensen@atlassian.com