Integrate CI/CD Pipelines with Jira Software Cloud

PATRICK STREULE | ARCHITECT | ATLASSIAN | @PSTREULE
Atlassian Document Format
…is coming to an API near you

Atlassian Editor
In Jira, Confluence,
Bitbucket, OpsGenie, …

Mentions
Code
Apps
Actions 
Decisions

WikiMarkup Markdown CXHTML
*Example Code*
{noformat}
const todo = items
.filter(
item => !item.done
);
{noformat}

*Example Code*
{noformat}
const todo = items
.filter(
item => !item.done
);
{noformat}
**Example Code**
```javascript
const todo = items
.filter(
item => !item.done
);
```

*Example Code*
{noformat}
const todo = items
.filter(
item => !item.done
);
{noformat}
**Example Code**
```javascript
const todo = items
.filter(
item => !item.done
);
```
<p>
<strong>Example Code</strong>
</p>
<ac:structured-macro
ac:name="code"
ac:schema-version="1"
ac:macro-id="5f5ca260…">
<ac:parameter ac:name="language">
js
</ac:parameter>
<ac:plain-text-body>
<![CDATA[const todo = …]]>
</ac:plain-text-body>
</ac:structured-macro>

Consistency
Learn a single format  
for all product APIs
Extensibility
Support for any  
new Editor feature
Why a new Format?

AtlassianDocumentFormat(ADF)
{
"type": "doc",
"version": 1,
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "Example Code",
"marks": [{ "type": "strong" }]
}
]
},
{
"type": "codeBlock",
"attrs": {
"language": "JavaScript"
},
"content": [
{
"type": "text",
"text": "const todo = items.filter(item => …);"
}
]
}
]
}

AtlassianDocumentFormat(ADF)
{
"type": "doc",
"version": 1,
"content": [
{
"content": [
{
"type": "text",
"text": "Example Code",
"marks": [{ "type": "strong" }]
}
]
},
{
"type": "codeBlock",
"attrs": {
"language": "JavaScript"
},
"content": [
{
"type": "text",
"text": "const todo = items.filter(item => …);"
}
]
}
]
}
{
"type": "doc",
"version": 1,
"content": [
{
"type": "decisionList",
"attrs": {
"localId": "862034fa..."
},
"content": [
{
"type": "decisionItem",
"attrs": {
"state": "DECIDED",
"localId": "09f1eb1e..."
},
"content": [
{
"text": "We need a new format",
"type": "text"
}
]
}
]
}
]
}

Processable
Easy to construct and parse
by machines
Why JSON?
Maintainable
Schema for documentation,
validation and backward
compatibility checks
Familiar
Lingua franca,  
supported everywhere

Verbose
Even in comparison with
Confluence CXHTML (1.6x)
Not a standard
The JSON schema is
Atlassian-specific
But…

BlockNodes
Paragraphs,Codeblocks,Quotes,…
DOCUMENT STRUCTURE: TERMINOLOGY

BlockNodes
InlineNodes
Text,Mentions,….

BlockNodes
InlineNodes
Text,Mentions,….
Marks
Bold,Italic,Links…

{
"type": "<type>",
"attrs": {},
"content": []
}
DOCUMENT STRUCTURE: BLOCK NODES

{
"type": "<type>",
"attrs": {},
"content": []
}
Type
Allnodesandmarks

{
"type": "<type>",
"attrs": {},
"content": []
}
Metadata
Anynodeormark
(optional)
Type
Allnodesandmarks

{
"type": "<type>",
"attrs": {},
"content": []
}
Metadata
Anynodeormark
(optional)
Type
Allnodesandmarks
Children
(optional)

{
"type": "<type>",
"attrs": {},
"text": "<text>",
"marks": [],
}
Metadata
Anynodeormark
(optional)
Type
Allnodesandmarks
DOCUMENT STRUCTURE: INLINE NODES

{
"type": "<type>",
"attrs": {},
"text": "<text>",
"marks": [],
}
Metadata
Anynodeormark
(optional)
Type
Allnodesandmarks
Text

{
"type": "<type>",
"attrs": {},
"text": "<text>",
"marks": [],
}
Metadata
Anynodeormark
(optional)
Type
Allnodesandmarks
Text
Formatting
(optional)

{
"type": "<type>",
"attrs": {}
}
Metadata
Anynodeormark
(optional)
Type
Allnodesandmarks
DOCUMENT STRUCTURE: MARKS

{
"version": 1,
"type": "doc",
"content": []
}
DOCUMENT STRUCTURE: EMPTY DOCUMENT

{
"version": 1,
"type": "doc",
"content": [
{
"content": [
{
"type": "text",
"text": "Some "
},
{
"type": "text",
"text": "formatted",
"marks": [
{
"type": "strong"
}
]
},
{
"type": "text",
"text": " content"
}
]
},
DOCUMENT STRUCTURE

"type": "text",
"text": " content"
}
]
},
{
"type": "panel",
"attrs": {
"panelType": "info"
},
"content": [
{
"content": [
{
"type": "text",
"text": "A panel"
}
]
}
]
},
{
"content": [
{
"type": "emoji",
DOCUMENT STRUCTURE

{
"content": [
{
"type": "emoji",
"attrs": {
"shortName": ":link:",
"id": "1f517",
"text": "🔗"
}
},
{
"type": "text",
"text": " "
},
{
"type": "text",
"text": "www.atlassian.com",
"marks": [
{
"type": "link",
"attrs": {
"href": "http://www.atla
}
}
]
DOCUMENT STRUCTURE

@atlaskit/adf-utils
Maintainedby
theAtlassianEditorteam

LIBRARIES: ATLASKIT ADF-UTILS
const {
doc, p, text, emoji, strong, panel, link
} = require('@atlaskit/adf-utils/builders');
const document = doc(

const {
p(
text('some '),
strong(text('formatted')),
text(' content')
),

const {
p(
text('some '),
text(' content')
),
panel({ panelType: 'info' })(
p(
text('A panel')
)
),

const {
p(
text('some '),
text(' content')
),
panel({ panelType: 'info' })(
p(
text('A panel')
)
),
p(
emoji({ shortName: ':link:' }),
text(' '),
link({ href: 'https://www.atlassian.com' })(
text('www.atlassian.com')
)
)
);

EXTRACTING ALL MENTIONED USERS

}
]
},
{
"type": "tableCell",
"attrs": {
"colspan": 1,
"rowspan": 1
},
"content": [
{
"content": [
{
"type": "mention",
"attrs": {
"id": "557057:46e75034-9ece-11e8-acd5-420039310d01"
"text": "@user4"
}
},
{
"text": " ",
"type": "text"
}
]
}
]
}
]
}
]
},
{
"content": [
{
"type": "mention",
"attrs": {
"id": "557057:509d96ec-9ece-11e8-bdff-420039310d01",
"text": "@user5"
}
},
{
"text": " to add more tasks",
"type": "text"
}
]
}
],
"version": 1
}

FILTER $
const { filter } = require(
'@atlaskit/adf-utils/traverse'
);
const accountIds = filter(
document,
node => node.type === 'mention'
).map(
node => node.attrs.id
);
console.log(accountIds);

FILTER $ node src/filter.js
);
document,
).map(
);

FILTER $
[ '557057:09f20a2a-9ece-11e8-998a-420039310d01',
'557057:2eee6792-9ece-11e8-9c9a-420039310d01',
'557057:3c603a90-9ece-11e8-9536-420039310d01',
'557057:46e75034-9ece-11e8-acd5-420039310d01',
'557057:509d96ec-9ece-11e8-bdff-420039310d01' ]
node src/filter.js
);
document,
).map(
);

TRAVERSE
const { traverse } = require('@atlaskit/adf-utils/traverse');
const linkified = traverse(document, {
text: (node, parent) => {
const match = node.text.match(/Task (d+)/);
if (match) {
return {
...node,
marks: [
{
type: 'link',
attrs: {
href: `https://tasks.example.com/task-${match[1]}`
}
}
]
}
}
}
});
console.log(JSON.stringify(linkified));
$

TRAVERSE
if (match) {
return {
...node,
marks: [
{
type: 'link',
attrs: {
}
}
]
}
}
}
});
$ cat document.json

TRAVERSE
$
if (match) {
return {
...node,
marks: [
{
type: 'link',
attrs: {
}
}
]
}
}
}
});
{
"content": [
{
"text": "Task 1",
"type": "text"
}
]
}
$ cat document.json

TRAVERSE
$ node src/traverse.js
if (match) {
return {
...node,
marks: [
{
type: 'link',
attrs: {
}
}
]
}
}
}
});
{
"content": [
{
"text": "Task 1",
"type": "text"
}
]
}
$ cat document.json

TRAVERSE
$ node src/traverse.js
if (match) {
return {
...node,
marks: [
{
type: 'link',
attrs: {
}
}
]
}
}
}
});
{
"content": [
{
"text": "Task 1",
"type": "text"
}
]
}
$ cat document.json
{
"content": [
{
"text": "Task 1",
"type": "text",
"marks": [
{
"type": "link",
"attrs": {
"href": "https://tasks.example.com/task-1"
}
}
]
}
]
}

RENDERING
import React, { Component } from 'react';
import { ReactRenderer } from '@atlaskit/renderer';
import { doc, p, text, strong } from '@atlaskit/adf-utils/builders';
p(
text('some '),
text(' content')
)
);
export default class MyComponent extends Component {
render() {
return (
<ReactRenderer document={document} />
);
}
}

TOOLS: REFERENCE DOCUMENTATION
Node Types
All node types that are
supported in a product,
along with their attributes.
Examples
How each node type is used in
practice.

TOOLS: ADF BUILDER
Usage
Create a document using the
editor and see the resulting
ADF.
Limits
Node types like mentions,
actions or images are not
supported.

TOOLS: ADF VIEWER
Usage
Paste an ADF document to
review how it
Limits
Node types like images or
smart links are not supported.

Examples & Links: 
https://bit.ly/atlascamp-adf

PATRICK STREULE | ARCHITECT | ATLASSIAN | @PSTREULE
Thank you!

Integrate CI/CD Pipelines with Jira Software Cloud

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to Integrate CI/CD Pipelines with Jira Software Cloud

Similar to Integrate CI/CD Pipelines with Jira Software Cloud (20)

More from Atlassian

More from Atlassian (20)

Recently uploaded

Recently uploaded (20)

Integrate CI/CD Pipelines with Jira Software Cloud