Patrick Streule You have an idea for an add-on? You want to tap into both the Atlassian Cloud and Server customer base without writing and maintaining it twice? Patrick illustrates some techniques you can use today to share most of your code between the Connect and the P2 add-on implementation.

1. Connect Add-ons for
Cloud & Server
PATRICK STREULE • ARCHITECT • ATLASSIAN • @PSTREULE

3. Connect

5. Overview

6. Cloud
Browser
Product – Cloud Add-On Service
Connect Plugin
Connect JS
Add-On UI
Add-On JS
AssetsAPI

7. Browser
Product – Cloud Add-On Service
Connect Plugin
Connect JS
Add-On UI
Add-On JS
AssetsAPI
Cloud Create iFrame,
XDM bridge

8. Browser
Product – Cloud Add-On Service
Connect Plugin
Connect JS
Add-On UI
Add-On JS
AssetsAPI
Cloud
Expose
Host API

9. Browser
Product – Cloud Add-On Service
Connect Plugin
Connect JS
Add-On UI
Add-On JS
AssetsAPI
Cloud
Lifecycle,
Webhooks

10. Browser
Product – Cloud Add-On Service
Connect Plugin
Connect JS
Add-On UI
Add-On JS
AssetsAPI
Cloud
REST API

11. Browser
Product – Cloud Add-On Service
Connect Plugin
Connect JS
Add-On UI
Add-On JS
AssetsAPI
REST API
Bridge
Cloud

12. Now in Server

13. Server
Product – Server v1
Product – Server v2
Browser
Add-On Service
?
Add-On UI
Add-On JS
AssetsAPI
Product – Server v3
?

14. Server
Product – Server v1
Product – Server v2
Browser
Add-On Service
?
Add-On UI
Add-On JS
AssetsAPI
Product – Server v3
?
iFrame setup?
XDM?
API Version?

15. Server
Product – Server v1
Product – Server v2
Browser
Add-On Service
?
Add-On UI
Add-On JS
AssetsAPI
Product – Server v3
?
Auth?
Privacy?
Connectivity?

16. Server
Product – Server v1
Product – Server v2
Browser
Add-On Service
?
Add-On UI
Add-On JS
AssetsAPI
Product – Server v3
?
Connectivity?
API Version?
Auth?

17. Example
Sequence Diagram Add-On

19. • Purely client-side
• No server-side rendering
• Javascript & SVG
• No data stored by the add-on
• Uses macro body for storage
• Uses REST API to fetch the macro
body
• However: The Connect version
stores the installation payload
Browser
Product – Cloud Add-On Service
Connect Plugin
Connect JS
Add-On UI
Add-On JS
Assets
Design Choices
ConnectP2
Browser
Product – Server
P2 Plugin
Add-On UI
Add-On JS
Assets
Connect JS Shim

20. Show me code

21. Plugin XML
<web-resource key="sequence-diagram-resources" name="sequence-diagram Web Resources">
<resource type="download" name="blueprint.css" location="/css/blueprint.css"/>
<resource type="download" name="confluence.css" location="/css/confluence.css"/>
<resource type="download" name="napkin.css" location="/css/napkin.css"/>
<resource type="download" name="plain.css" location="/css/plain.css"/>
<resource type="download" name="sequence-diagrams.js" location="/js/sequence-diagrams.743cf0e5.js"/>
<resource type="download" name="connect-api.js" location="/js/connect-api.js"/>
<resource type="download" name="addon.js" location="/js/addon.js"/>
</web-resource>
<servlet name="Diagram IFrame Servlet" key="sequence-diagram-servlet" class="com.pstreule.SequenceDiagramIFrame">
<url-pattern>/sequence-diagram</url-pattern>
</servlet>
<xhtml-macro name="sequence-diagram" class="com.pstreule.SequenceDiagramMacro" key="sequence-diagram-macro">
<parameters>
<parameter name="theme" type="enum" required="true">
<value name="Confluence"/>
<value name="Blueprint"/>
<value name="Napkin"/>
<value name="Plain"/>
</parameter>
<parameter name="width" type="string"/>
</parameters>
</xhtml-macro>

22. Render the iFrame
public SequenceDiagramMacro(TemplateRenderer renderer, ApplicationProperties applicationProperties)
{
this.renderer = renderer;
this.applicationProperties = applicationProperties;
}
@Override
public String execute(Map<String, String> parameters, String storageFormatBody, ConversionContext conversionContext)
throws MacroExecutionException
{
ContentEntityObject entity = conversionContext.getEntity();
String baseUrl = applicationProperties.getBaseUrl();
URI uri = UriBuilder.fromPath(baseUrl + "/plugins/servlet/sequence-diagram")
.queryParam("pid", entity.getIdAsString())
.queryParam("pv", entity.getVersion())
.queryParam("mh", DigestUtils.md5Hex(storageFormatBody))
.queryParam("theme", parameters.get("theme"))
.build();
Map<String, Object> context = new HashMap<>();
context.put("url", uri.toString());
context.put("name", "preview".equals(conversionContext.getOutputType()) ? storageFormatBody : "");
return render("/templates/iframe.vm", context);
}
<iframe src="$url" name="$name" frameborder="0"
rel="nofollow" scrolling="no"></iframe>

23. Render the iFrame Content
public class SequenceDiagramIFrame extends HttpServlet
{
private final TemplateRenderer renderer;
private final PageBuilderService pageBuilderService;
public SequenceDiagramIFrame(TemplateRenderer renderer, PageBuilderService pageBuilderService)
{
this.renderer = renderer;
this.pageBuilderService = pageBuilderService;
}
@Override
protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException
{
resp.setStatus(HttpServletResponse.SC_OK);
resp.setContentType("text/html");
StringWriter writer = new StringWriter();
WebResourceAssembler assembler = pageBuilderService.assembler();
assembler.assembled().drainIncludedResources();
assembler.resources().requireWebResource("com.pstreule.sequence-diagram:sequence-diagram-resources");
WebResourceSet set = assembler.assembled().drainIncludedResources();
set.writeHtmlTags(writer, UrlMode.RELATIVE);
renderer.render("/templates/sequence-diagram.vm",
Collections.singletonMap("resourcesWithHtml", writer.toString()), resp.getWriter());
}
}
<html>
<head>
$resourcesWithHtml
</head>
<body>
<div id="sequence-diagram"></div>
<script type="application/javascript">
renderSequenceDiagram("sequence-diagram", window.name)
</script>
</body>
</html>

24. Add-On JavaScript Code
function renderSequenceDiagram(id, previewMacroBody) {
function render(diagramCode) {
function onRenderSuccess(dimensions) {
AP.resize(dimensions.w + 10, dimensions.h + 10);
}
var themeName = Loader.getUrlParameter("theme");
var theme = SequenceDiagramThemes.byName(themeName);
var controller = new SequenceDiagramController(id);
controller.renderSequenceDiagram(diagramCode, theme, null, onRenderSuccess, onRenderError);
}
function loadMacroAndRender() {
function onLoadSuccess(responseBody) {
var diagramCode = JSON.parse(responseBody).body;
render(diagramCode);
}
AP.require(['request'], function (request) {
var pageId = Loader.getUrlParameter("pid");
var pageVersion = Loader.getUrlParameter("pv");
var macroHash = Loader.getUrlParameter("mh");
request({
url: "/rest/api/content/" + pageId + "/history/" + pageVersion + "/macro/hash/" + macroHash,
success: onLoadSuccess
});
});
}
loadMacroAndRender();
}

25. Connect JS Shim
var AP = {};
(function (AP) {
var AJS = window.parent.AJS;
var $ = AJS.$;
_modules = {
'request': function (url, args) {
…
$.ajax({
url: url,
…
}).then(done, fail);
}
};
AP.require = function (modules, callback) {
var requiredModules = Array.isArray(modules) ? modules : [modules];
var args = requiredModules.map(function (module) {
return _modules[module];
});
callback.apply(window, args);
};
AP.resize = function (width, height) {
AJS.$(window.frameElement).css({width: width, height: height});
};
})(AP);

26. Best Practices

27. Make it
Self-Contained

28. Run in Process
Browser
Product – Server
P2 Plugin
Add-On UI
Add-On JS
AssetsAPI
Connect JS Shim
Adapter

29. Run in Process
Browser
Product – Server
P2 Plugin
Add-On UI
Add-On JS
AssetsAPI
Connect JS Shim
Adapter
No cross-domain
bridge needed

30. Run in Process
Browser
Product – Server
P2 Plugin
Add-On UI
Add-On JS
AssetsAPI
Connect JS Shim
AdapterEvent Handling,
Storage

31. Run in Process
Browser
Product – Server
P2 Plugin
Add-On UI
Add-On JS
AssetsAPI
Connect JS Shim
Adapter
100% Reusable
100% Reusable

32. Run in Process
Browser
Product – Server
P2 Plugin
Add-On UI
Add-On JS
AssetsAPI
Connect JS Shim
Adapter
100% reusable
(maybe)

33. Use Client-Side
Rendering as much
as Possible

34. Shrink the server-side
Browser
Product – Server
P2 Plugin
Add-On UI
Add-On JS
AssetsAPI
Connect JS Shim

35. Use In-Product
Data Storage

36. Use Entity Properties for Data Storage
POST /rest/api/content/{content_ID}/property
Content-Type: application/json
{
"key" : "attachment",
"value" : {
"size": 234374,
"description": "My description"
...
}
}
GET /rest/api/content/{content_ID}/propertyGET /rest/api/2/issue/{key}/properties/
PUT /rest/api/2/issue/{key}/properties/
attachment
Content-Type: application/json
{
"size": 234374,
"description": "My description"
...
}

37. Use Entity Properties for Data Storage
{
"jiraEntityProperties": [
{
"keyConfigurations": [
{
"propertyKey": "attachment",
"extractions": [
{
"objectName": "attachment.size",
"type": "number",
"alias": "attachmentSize"
}
]
}
],
"entityType": "issue",
"name": {
"value": "Attachment Index Document"
}
}
]
}
{
"confluenceContentProperties": [
{
"keyConfigurations": [
{
"propertyKey": "attachment",
"extractions": [
{
"objectName": "attachment.size",
"type": "number"
}
]
}
],
"name": {
"value": "Attachment Index Document"
}
}
]
}

38. Use client-side REST Calls
// Get the content properties of an issue
AP.require(['request'], function(request){
request({
url: '/rest/api/2/issue/' + issueKey + '/properties/',
success: function(responseText){
var properties = JSON.parse(responseText);
…
}
});
});

39. Expose REST API
for Server-Side
Logic

40. JAX-RS/Jersey
@Path("my-resource")
public class MyResource
{
@GET
@Produces("application/json")
public Response getSomething(@Context HttpServletRequest request)
{
// ...
return Response.ok();
}
}

41. Tools*
*currently in planning

42. Thank you!
PATRICK STREULE • ARCHITECT • ATLASSIAN • @PSTREULE

43. Connect everywhere - Cloud and Server
Submit your feedback:
go.atlassian.com/acconnectcloud