AtlasCamp 2014: Writing Connect Add-ons for Confluence
53
June 3-5, 2014 | Berlin, Germany
-
Upload
atlassian -
Category
Technology
-
view
351 -
download
4
description
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.
Transcript of AtlasCamp 2014: Writing Connect Add-ons for Confluence
June 3-5, 2014 | Berlin, Germany
@matthewjensen
Matthew Jensen, Confluence Ecosystem, Atlassian
Writing Connect Add-ons for Confluence
• About Me:!• Almost 7.5 years at Atlassian
Introduction
81%
19%
• About Me:!• Almost 7.5 years at Atlassian!• Over four years on Confluence
development
Introduction
81%
9%
10%
Why is it so hard to write a Confluence plugin?
— Matthew Jensen, Confluence Ecosystem”
“
Confluence Ecosystem
Confluence Platform
Spac
es
Que
stio
ns
? ?????
Connect and
Confluence
SAMEBUT DIFFERENT
SAME
Confluence Connect
DESIGN
SECURITY
PERFORMANCE
MACROS
HiliteMeM AC R O S
Example
Consider a macro to pretty print your code
M AC R O S
ExampleM AC R O S
This macro can make any code look great!
Example
http://bitbucket.org/mjensen/hilite-me-addon
M AC R O S
• Can be of any size!• Can contain sensitive information
Macro Body
CONFIDENTIAL
M AC R O S
• Only use HTTP GET operations!• Flexibility!• This concern is new with Connect
Macro BodiesM AC R O S
VSDynamic Macros
Static Macros
Dynamic Content MacrosConfluence Add onBrowser
Request
HTML
IFrame
Unformatted Code
Formatted
Requested
Returned
Macro Loaded
M AC R O S
• 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 MacrosM AC R O S
Static Content MacrosConfluence Add onBrowser
Request
Unformatted Code
Formatted Code
Requested
Returned
M AC R O S
• 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 MacrosM AC R O S
• 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 MacroM AC R O S
Confluence Connect
DESIGN
SECURITY
PERFORMANCE
MACROS
Example
• Consider a simple connect macro to include a status indicator on your page!
• Status as a parameter, and no body.
P E R F O R M A N C E
ExampleP E R F O R M A N C E
http://bitbucket.org/mjensen/status-addon
Static Content MacrosConfluence Add onBrowser
status=Awesome
Awesome
Requested
Returned
P E R F O R M A N C E
Cached
• 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
P E R F O R M A N C E
• 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
P E R F O R M A N C E
• 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
P E R F O R M A N C E
Body as a ParameterConfluence Add onBrowser
Rendered
Requested
Returned
body=Awesome
P E R F O R M A N C E
Cached
• Body is limited to 128 characters!• May appear in Confluence logs!• May be tracked in caches or proxies
Body as a ParameterP E R F O R M A N C E
• Some integrations happen synchronously!• Remote Conditions and Static Content Macros
Synchronous Callbacks
Confluence Add onBrowser
Request
Slow Response
!#$
P E R F O R M A N C E
Confluence Connect
DESIGN
SECURITY
PERFORMANCE
MACROS
Do you need to store any data at all?
Data StorageS E C U R I T Y
Web Security
Vulnerable area
Permitted to user Permitted to add on
S E C U R I T Y
READADMIN
• 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
S E C U R I T Y
Confluence Connect
DESIGN
SECURITY
PERFORMANCE
MACROS
• Static add ons contain only html and javascript files
Static Add Ons
Confluence Add onBrowser
D E S I G N
Coming Up
BlueprintsC O M I N G U P
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
C O M I N G U P
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
C O M I N G U P
BlueprintsC O M I N G U P
BlueprintsC O M I N G U P
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!
C O M I N G U P
CQLC O M I N G U P
We need you!
Yes you!
C O M I N G U P
