Overview

JSON (JavaScript Object Notation) has become a highly used interchange format because of its lightweight, simplicity, and ability for humans to read and write easily. Many REST APIs produce JSON format and the format is used predominantly in Atlassian REST APIs. There is also an abundance of support libraries associated with the format which makes it ideal for scripting output.

The JSON table macro can import, format and display JSON (JavaScript Object Notation) data from anywhere, by:

Reading the JSON data from any of these sources:
1. Within your Confluence page.
2. From a file residing on the Confluence server (Server only).
3. From a Space Template (Server only).
4. From a page attachment.
5. From an external URL.
Allowing customizable access to fields.
Supporting inclusion of Wiki Markup macros within the JSON data.
Combining with the Chart macro to produce powerful data visualization.
Leveraging the same table styling capabilities as the Table Plus macro.

This macro supports Common table capabilities.

Available in plugin release 6.3 and above.

Applicable upto app version 8.1:

To enable using HTML content with JSON data, you must enable the Stop encoding of html characters parameter. In such a case, it is recommended to contact your administrator to use Macro Security for Confluence with this app to provide an additional layer of security to your data and privacy. Refer to this documentation to for more information on the Macro Security for Confluence app.

From app version 8.2 onwards, if the Stop encoding of html characters parameter is enabled, use of Macro Security for Confluence is no longer needed as the macro itself provides additional security to your data.

Basic Use

This macro can be deployed using one of the following methods:

Selected from the Macro Browser	JSON Table
Markup Shortcut	{json-table}

Screenshot

Parameters

Click a column heading to toggle the sorting of that column.

Parameter	Default	Macro Browser Label	Description
paths	<required>	Paths to fields	Normally, specify a single path to generate a single table. Simple form is a dot separated list of field names to reach the specific field within the JSON string. Example: total.monthlies. When a comma separated list of paths to fields is provided, a table will be produced for each valid field identified by the path. No table will be produced for references to fields that cannot be found, empty arrays, or similar. Paths are expressed in JSONPath syntax.
fieldPaths	all fields	Paths to fields to be included	Comma separated list of paths to fields to be included in the output. Paths are relative to the JSON field specified in the paths parameter. If not specified, all fields found will be included. Example for the issues field from the JIRA search REST API: *key, fields.summary, fields.issuetype.name, fields.issuetype.id, fields.fixVersions[].name**
fieldOrderRegexPatterns		Regex patterns for ordering fields	Comma separated list of regular expression (regex) patterns. This parameter is used only when defaulting fieldPaths to all fields; otherwise the order specified by fieldPaths is used. Useful when multiple tables are generated and column ordering is not ideal. Field order is not specific in JSON strings so when field order is important, these Regex patterns can be used to control the order. Note: A field found by an earlier pattern is ordered before fields not found or fields found by a later pattern.
sortPaths		Paths used to determine sort order	Comma separated list of path references to fields (simple only) to be used to determine how rows will be initially sorted. Paths are relative to the JSON field specified in the path parameter. If specified, JSON array elements will be sorted based on the comparison of field values represented by the paths. The first path is the primary sort value. Subsequent paths are used only if the first comparison is equal. The sort direction is ascending unless the sortDescending is selected. This sorting is done before the HTML is generated for display.
stripQualifiers	false	Strip leading qualifiers from generated headings	Since 6.5. Makes table heading columns look better by stripping leading qualifiers (using a . separator) for names generated as a result of fieldPaths. For example, field.type would be converted to type.
capitalize	true	Capitalize first character of generated headings	Since 6.5. Makes table heading columns look better by capitalizing leading character of names generated as a result of fieldPaths.
output	html	Output format	Determines how the output is formatted. Allowable values are 'html' and 'wiki'. Use 'wiki' to have the data in the table rendered by the wiki renderer.
script	macro body	Location of JSON data	JSON data is taken from the macro body data unless another location is specified by the script or url parameters. ^attachment - Data is read from an attachment to the current page. page^attachment - Data is read from an attachment to the page name provided. space:page^attachment - Data is read from an attachment to the page name provided in the space indicated. Additional options available for Server only. #filename - Data is read from the file located in confluence home directory/script/filename. Subdirectories can be specified. global page template name - Data is read from a global page template. Special note: How to deal with templates on Confluence 4.3 and later. space:page template name - Data is read from a space template.
url		URL to JSON data	Specifies the URL to a JSON file. Use of this parameter may be restricted for security reasons. See your administrator for details.
user		URL user	User name for URL access via basic authentication.
password		URL user password	User password for URL access via basic authentication.
timeout		URL connection timeout	Allows you to set the wait time for URL access for slower connections. Time is specified in milliseconds.
encoding		File encoding	File encoding for an external file if different from the system default handling. Since 4.1.0. Example: UTF-8. More ...
columns		Columns to show	Comma separated list of column names or numbers in any order. Defaults to all columns in existing order. Columns are enumerated starting at 1.
showWiki	false	Show non-formatted version of generated wiki	Use true to show a non-formatted version of the wiki table following the formatted table. This is used to help resolve formatting issues. It can also be used to convert JSON to Confluence markup by cut and paste.
escape	false	Escape special wiki characters	When wiki output is requested (output=wiki), some special characters (like '\|', '[', ']', '{', '}') in data may cause undesirable formatting of the table. Use true to allow these special characters to be escaped so that it will not affect the formatting. The default is false so that data that has wiki markup will be handled correctly.
macros	false	Render wiki markup macros in body	Set to true to render wiki markup macros found in the body prior to processing as JSON. This is useful to run macros from Scripting for Confluence, Run CLI Actions in Confluence, SQL for Confluence, or similar that can produce JSON output.
disableAntiXss	false	Stop encoding of html characters	Server only. Set this parameter to true for csv tables that use output=html and have html content. Html content like <a href=http://google.com>google</a> will only display as a link if this parameter is enabled. Your administrator must grant specific users or groups to use this capability using Macro Security for Confluence.

Augment parameters

See Augments for details for modifying column headings and column data.

Common parameters

The following parameters are part of our common table capabilities that are available to many macros that produce or modify tables.

Click a column heading to toggle the sorting of that column.

Parameter

Default

Macro Browser Label

Description

heading

1

Heading rows

Number of rows to be considered as heading rows. Heading rows do not participate in column sorting.

footing

0

Footing rows

Number of rows to be considered as footing rows. Footing rows do not participate in column sorting.

enableSorting

true

Enable column sorting

Set to false to disable sorting.

enableHighlighting

true

Enable row highlighting on mouse over

As the mouse moves over a table row, the row will be highlighted by default. Set to false to stop this behavior.

sortColumn

Auto sort column

The table can be auto sorted before it is displayed by any valid column name or number provided by this parameter. No auto sorting will be done if this value is not provided or is invalid. A column number is a 1-based count of columns (excluding auto number column).

sortDescending

false

Sort descending

If sortColumn is used, this determines the order of the sort that is automatically done before display.

sortTip

Sort tip on mouse over

Text displayed when mouse is over a sortable column. Normally, this value is Click to sort or equivalent translation.

sortIcon

false

Show sort icon

Use true to include a sort icon in the first heading row for sortable columns. An icon will show for the last column sorted indicating the direction the column was sorted.

highlightColor

lightgoldenrodyellow

Highlight color

Color of row when mouse is over a row element. See Web Colors for instructions on how to specify this.

autoNumber

false

Auto number on each row

Use true to show an additional column that show row number for each data row.

autoNumberSort

false

Auto number sort

Use true to enable the auto number column to be sortable. This will retain the original data row count even after row sorting.

autoTotal

false

Auto total row

Use true to append a row to the end of the table that will contain totals of all numeric columns.

allowExport

false

Allow download and export

Enable user to download or export the current view of the table as a CSV file. Download is to the local file system. Export is to an attachment to the current page and is only available to users that have permission to add attachments to the page. When enabled, download and export icons will be available to the right of the table. This is a new option starting with Advanced Tables 7.2, SQL 8.3, and Excel 6.3.

columnTypes

Column types

Column types determine how column data is sorted and displayed. By default, column data is treated as a text string sorted alphabetically. Some macros, like the SQL and CSV macros, may automatically generate more precise types. When the default behavior is less than optimal for your situation, the columnTypes parameter can be set specifically. This describes the behavior of the various types. In addition, numeric types are right aligned and can result in a total row entry.

Type	Description	Sorting
S	Text string. This is a series of one or more alphanumeric characters, possibly including a letter, number, space, punctuation mark or other special characters.	Alphabetic
I	Integer. This is a numeric field without a fractional component.	Numeric
F	Numeric or float value and may contain numeric separators including a decimal point and a comma for thousands separator.	Numeric
FF	Numeric or float value and may contain numeric separators including a decimal point and a comma for thousands separator. Forced formatting of data columns.	Numeric
FC	Numeric or float value and may contain numeric separators including a comma for decimal separator and a period for thousands separator.	Numeric
C	Similar to F with more leniency on leading and trailing characters to allow currency and similar symbols to be present and ignored.	Numeric
CC	Similar to FC with more leniency on leading and trailing characters to allow currency and similar symbols to be present and ignored.	Numeric
M	Date format in many popular formats. See Advanced Date Sorting for more information. This is the preferred date sorting type.	Date
D	Date in the browser date format. See Advanced Date Sorting for more information. The D type is available for compatibility with older releases - the M type is recommended.	Date
E	Emoticons or other HTML elements.	Alphabetic on the inner HTML value
X	Indicates to exclude this column from user selectable sorting.	Disabled
.	Separated numbers, like phone numbers or TCP addresses. Valid values are multiple integer numbers separated by '.'.	Numeric on each separated value
:	Separated numbers, like phone numbers or TCP addresses. Valid values are multiple integer numbers separated by ':'.	Numeric on each separated value
-	Separated numbers, like phone numbers or TCP addresses. Valid values are multiple integer numbers separated by '-'.	Numeric on each separated value
/	Separated numbers, like phone numbers or TCP addresses. Valid values are multiple integer numbers separated by '/'.	Numeric on each separated value
H	Indicates to hide the column.

Total formatting - option to format the total row in a user defined way. See Formatting the Auto Total Row for Numeric Columns.
Numeric data formatting - option to format the data rows in a user defined way for numeric columns. See Formatting Options for Numeric Columns.
Date data formatting - option to format the data rows in a user defined way for date columns. See Formatting Options for Date Columns.

Example Use

Column types: S,I,F"0,0",F"$0,0.00"

columnCalculations

Column calculations

When an auto total parameter is selected, this parameter can be used to customize the calculation or text that is shown on the total row. By default, all numeric fields, as specified by column types, are totaled. By specifying a comma separated list of calculation requests, the behavior can be modified using special values for the corresponding column.

Type	Result
sum	Column entries are totaled. The column type must be numeric.
avg	Column entries are totaled and then divided by the number of data rows. The column type must be numeric.
avgIgnoreZero	Column entries are totaled and then divided by the number of data rows that are non-zero and non-blank. The column type must be numeric. Requires Table Library 3.5 and above.
max	The largest data value among the column entries is returned. The Column type must be numeric.
min	The smallest data value among the column entries is returned. The Column type must be numeric.
<other text>	Any other text including a blank field will be copied to the corresponding total row field. No calculations are done.

The Max and Min Total type is available only for Advanced Tables for Confluence: Server and Data Center.

rowStyles

Table row styles

A comma separated list of styles. Each style is made up of one or more properties. The first is applied to all heading rows determined by the heading parameter. The remaining styles are applied to the remaining rows in order with repetition as necessary. A style can be reused for subsequent rows by referring to it using a 1-based numeric reference. Row styles are applied to the table row and participate with other CSS properties to determine the look of an element. In particular, some properties may be overridden by table or element styles or classes.

Example: , background:lightyellow, background:lightblue

retainRowStyleOrder

true

Retain row style order after sorting

When selected, the row styles correspond to the order the rows are displayed on the screen. When not selected, the original style given to a row is retained not matter where the row lands after sorting.

columnStyles

Column styles

Comma separated list of styles. Each style is made up of one or more CSS properties (semi-colon separated). The styles are applied to columns in sequence. If a column is skipped, supply a comma before adding the next columns style. A style can be reused for subsequent columns by referring to it using a 1-based numeric reference. Column styles are applied to the table column and participate with other CSS properties to determine the look of an element. In particular, some properties may be overridden by table, row, or element styles or classes.

Example: background:lightyellow, background:lightblue,1,2,1,2

columnAttributes

Column attributes

A comma separated list of values used to modify cell attributes for all cells in a column. The position in the comma separated list corresponds to the column that the values apply to. Each value is a double semi-colon list of attributeName=value pairs that will be applied to the column cells.

enableHeadingAttributes

true

Enable heading attributes

Any column attributes provided will be applied to the all column rows including heading rows. Use false to have the column attributes apply only to data rows.

id

auto generated

Table id

Table id can be referenced for use in macros (like the chart macro) or javascript.

class

@default

Table class

Sets the class of the table. Normally, it will be confluenceTable. Use a blank (one or more spaces) value to not have any table class.

style

Table style

Style attributes can be set. For example: font-style:italic; background:lightblue;.

width

Table width

In pixels or %. Recommend using style settings instead.

border

Table border width

In pixels. Set class to blank also. Recommend using style settings instead.

Examples

Filter by label

There are no items with the selected labels at this time.

Compatibility

Chart Macro - the JSON Table Macro can be used to create data for a chart
Beanshell macro - can be used to generate JSON Table Macro and data as output from Java code (use output=wiki)
Groovy macro - can be used to generate JSON Table Macro and data as output from Groovy code (use output=wiki)
Jython macro - can be used to generate JSON Table Macro and data as output from Jython code (use output=wiki)

JSON Table Macro

On this page

Overview

Basic Use

Screenshot

Parameters

Augment parameters

Common parameters

Examples

Filter by label

Compatibility

Other Macros

Filter by label

Additional References