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

Questions?@matthewjensen

[email protected]