Dealing with Rich Text in Cloud

Up until version 3.0.16 Power Scripts knew only to set very simple text.

The document format (ADF) that governs the Atlassian rich text is fairly complex therefore we decided to present you with a simpler form of entering text in description & environment standard fields, comments, worklog comments, or any other rich text fields you may configure in your Jira and have internally an ADF representation associated with them.

Important!

Note that the standard custom fields provided by Atlassian and named Text Field (single line), Text Field (read only) are NOT ADF fields.

The below syntax should work on custom fields of type Text Field (multi-line) and all the above-mentioned fields and comments.

Paragraphs and Basic Decorations

A paragraph is any text that ends in a \n. Within the paragraph, you are allowed to add decorations to your text:

This is a very simple paragraph.

This is another paragraph containing text in **bold** , //italics//, ~~strike through~~ and __underline__.

This is another paragraph containing {{color: #2266AA}} colored text{{/color}}.

And another paragraph containing emojis: {{emoji}}🙂||:slight_smile:||1f642{{/emoji}}

Mentioning somebody need to follow this syntax {{mention}}@Radu Dumitriu||6093b81a539c14006ad3c137{{/mention}}

Let's not forget subscript--text-- and SuperScript^^text^^.

Links syntax: [[https://google.com||Google]].

There’s a lot going on here, so let’s summarize:

Decoration	Text	Obs
bold text	`bold text`
italics	`//italics//`
strike through	`~~strike through~~`
underline	`__underline__`
^superscript	`^^superscript^^`
_subscript	`--subscript--`
break in paragraph	{{break}}	No ending tag. Breaks in paragraphs.
color text	`{{color: #FF0000}} color text{{/color}}`	There should be no spaces before `:` Color is always hex
`🙂`	`{{emoji}}char\|\|text\|\|emoji_id{{/emoji}}`	Do not try to invent the ids, they are standard
mention	`{{mention}}@name\|\|uid{{/mention}}`	Must contain `@` right after `{{mention}}`
links	`[[url\|\|link text]]`	url and a text
inline code	``code here``

Example

description += "Examples: **bold** , //italics// or ~~strike through~~ and __underline__.\n";
description += "Links are given like this: [[https://google.com||Google text that appear]].\n";
description += "This is some {{color: #2266AA}} colored text{{/color}} followed by normal text.\n";
description += "Emojis: {{emoji}}🙂||:slight_smile:||1f642{{/emoji}} {{emoji}}😄||:smile:||1f604{{/emoji}} or a custom one {{emoji}}🎺||:trumpet:||1f3ba{{/emoji}}\n";
description += "A mention: {{mention}}@Radu Dumitriu||6093b81a539c14006ad3c137{{/mention}}\n";
description += "A--Subscript-- and A^^Superscript^^\n";

Result is:

To escape characters, you will need to use \. For example:

\-\- will not be treated as subscript text \-\-

of course, in the language, do not forget that in strings you will need to double that backslash:

Headers

Headers are easy, it’s the normal syntax, there are 6 levels of headers. They must be on a separate line and the line should begin with the header marker:

Horizontal lines are created by adding a line with dashes, like so:

Example

Result:

Lists

Bullet Lists

Lines starting with * and terminated by a \n. Multiple lines, one after the other may be used to create a list

Example

Result:

Ordered lists

Lines starting with - and terminated by a \n. Multiple lines, one after the other may be used to create a list

Example

Result:

Quotes

Lines starting with > and terminated by a \n. Multiple lines, one after the other may be used to create a full quote

Example

Result:

Code Blocks

Inline code may be marked using ``. For code blocks, you will need to use ``` optionally followed by the language:

Again, you will need to use \n to mark the beginning and the end of a code block, they must be on separate lines.

Example

Result:

Panels

We opted for a HTML-like syntax for panels and tables, since people seem more comfortable with that. Panels must start on a new line.

Panels may contain rich text, but in order for it to be interpreted as such, you will need to mark it:

Please note that the markers for rich text are written on a separate line. They always must come in pairs <! !>.

Example

The example corresponding to the above is:

Result:

Tables

Tables follow a simplified html syntax as well. You will need to define the beginning of the table and its end on a new line

Simple Tables

Syntax for simple tables is the usual one:

Example

You will notice that the last row has cells with a defined colspan. Other attributes for cells are rowspan and background. More about that in the next chapter

Result:

Decorated Tables

You may apply some basic styling to your table. If your table header starts with:

you will define a table with numbered rows. Layout may be one of the following:

default - fits whatever space is available, excluding text margins
full-width - goes full width of the page
wide - allows the table to bleed into the text container margins

At the cell level, you may apply also some properties:

where the C and R are the colspan and the rowspan properties values, numeric. The background property is the color of the background for that cell.

NOTE: Both <table: and <td: must have the : character immediately after, no space allowed, i.e. <table : and < td : will yield parse errors!

Complex Cells

…and we’re not talking here about eukaryotes! Because cells may contain very complex elements, you may add the necessary escapes to let the parser know you are adding very complex content into that cell:

Again, you must use <! and !> on separate lines and add your content between those markers.

Example

We will modify the above table to have some complex cells as well:

Result:

Files & Media

Media and files embedded in the rich text are represented in this way:

Here:

uuid is internal and represents the attachment
type is the type of the attachment, e.g. file
collection and occurence are internal to Atlassian
width and height are the placeholder dimensions

Single media may have its layout specified like above.

Notes & Unsupported Text

We do not support fully the Atlassian Document Format, specifically we do not support InlineCards. This is a target for further developments, so notify us if you need them.

Not all constructs we allow are supported by Atlassian! If you receive a 400 (bad request) make sure your text follows the guidelines listed here: https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/ . Make sure you do not embed tables in tables or use any other constructs that are unsupported by Atlassian.

If you send a malformed document, we may wrap it, in certain cases, in an error document listing the errors encountered in the text.

If you correct the text and save it in a file, you may reapply the formatting using a very simple SIL script, like so:

Examples

Dynamic tables

The following example uses countries.csv as a data file, but to speak the truth, your data may come from anywhere. The automation uses a listener on the “Issue Commented“ event, gets the last comment and tries to see if you specified a part of the name of a county, then gets the data from the CSV file and amends the description of the issue.

Adding a comment like this one:

results in the description being enriched with the following data:

1 Paragraphs and Basic Decorations
- 1.1 Example
2 Headers
- 2.1 Example
3 Lists
- 3.1 Bullet Lists
  - 3.1.1 Example
- 3.2 Ordered lists
  - 3.2.1 Example
4 Quotes
- 4.1 Example
5 Code Blocks
- 5.1 Example
6 Panels
- 6.1 Example
7 Tables
- 7.1 Simple Tables
  - 7.1.1 Example
- 7.2 Decorated Tables
- 7.3 Complex Cells
  - 7.3.1 Example
8 Files & Media
9 Notes & Unsupported Text
10 Examples
- 10.1 Dynamic tables