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:
- Within your Confluence page.
- From a file residing on the Confluence server.
- From a space template.
- From a page attachment.
- 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 certain Common table capabilities.

Available from 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 for more information on 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	Advanced Tables - JSON Table
Markup shortcut	{json-table}

Screenshot

Parameters

JSON settings

Macro editor label	Default	Description	Macro parameter
Data source
Method of locating JSON data	macro body	Select the source of the JSON data from a drop-down with a list of options where JSON data is located. The included data follows the body data based on the location selected. Attachment - Data is read from the list of options selected for the following parameters: Space - Lists all available spaces. Page - Lists all the pages available from the selected space. The following options indicate: @self - current space or page @home - homepage of current space @parent - parent page of current page or space While previewing the page before publishing for the first time, the result for @parent may not be displayed as expected. Once you save the document, you can view the result as expected. Attachment - Lists all the attachments from the selected page. Filename - Data is read from the input specified in the File name field. You can specify the file located in Confluence home directory/script/filename, also subdirectories. Template - Data is read from a global page template specified in the Name of the template field. Special note: How to deal with templates on Confluence 4.3 and later. URL - Data is read from the URL of JSON data, Username, Password, and Connection timeout fields that are explained in the succeeding rows. Profile - Data is read from external applications such as GitLab and GitHub with a pre-defined set of parameters. If selected, you must then specify the profile (Profiles) and the URL (URL of CSV data) of the CSV file(s). Available from 8.1.0 version. This option appears only if at least one profile exists in your instance. For more information about profiles, refer to the Configuration documentation.	script
Profiles		Select a profile to be used to connect to a specific remote location. Contains a list of all profiles that are configured for this instance. Administrators configure a profile to connect to a remote location using a base URL and users then provide the relative path to the actual location of the JSON file in URL of JSON data. Appears if Method of locating CSV data is set to Profile. Available from 8.1.0 version.	profile
URL of JSON data		Enter the URL to a JSON file. If a profile is specified the Profiles field, enter the relative path of the actual location of the CSV file(s) here. Support of profiles is available from 8.1.0 version. Use of this parameter may be restricted for security reasons. See your administrator for details.	url
Username (if required)		Enter the user name to be used for URL access to JSON files.	user
Password (if required)		Enter the user password to be used for URL access to JSON files. The Password is encrypted and remains secure (available from version 8.6.0). If the first attempt fails while decrypting the password, the JSON Table macro initiates three retry attempts to decrypt the password. (Available since app version 8.7.1.)	password
Connection timeout		Enter time in milliseconds to wait until the URL connection times out before getting data. Use this to increase time needed for slow connections. Note that if a zero is given, the connection may wait indefinitely.	timeout
File encoding		Specify the encoding for an external file, if different from the system default handling. Example: UTF-8. Refer to this article for more information. Available from 4.1.0 version.	encoding
Data format
Paths to fields	<required>	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 is produced for each valid field identified by the path. No table is produced for references to fields that cannot be found, empty arrays, or similar. Paths are expressed in JSONPath syntax.	paths
Paths to fields to be included	all fields	Enter a 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 are included. Example for the issues field from the Jira search REST API: key, fields.summary, fields.issuetype.name, fields.issuetype.id, fields.fixVersions[].name*	fieldPaths
Regex patterns for ordering fields		Enter a comma-separated list of regular expression (regex) patterns. This parameter is used only when the Paths to fields to be included field defaults to all fields; otherwise, the order specified in Paths to fields to be included 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. A field found by an earlier pattern is ordered before fields not found or fields found by a later pattern.	fieldOrderRegexPatterns
Paths used to determine sort order		Enter a comma-separated list of path references to fields (simple only) to be used to determine how rows are initially sorted. Paths are relative to the JSON field specified in the Paths to fields parameter. If specified, JSON array elements are 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 Sort descending is selected. This sorting is done before the HTML is generated for display.	sortPaths
Data settings
Columns to display		Enter a comma-separated list of column names or numbers in any order. By default, all columns are displayed in its existing order. Columns are enumerated starting at 1.	columns
Output format	html	Specify how the output is formatted. The options are as follows: html - data is entered as standard HTML directly in the macro body. wiki - data in the table rendered using the wiki renderer.	output
Strip leading qualifiers from generated headings	Off	Enable this option to make table heading columns look better by stripping leading qualifiers (using a dot separator (.)) for names generated as a result of Paths to fields to be included. For example, field.type is converted to type. Available from 6.5 version.	stripQualifiers
Show result as table	On	Disable this option to display the JSON data as plain text without any whitespace or column delimiters. By default, the JSON data is rendered in a tabular format. Available since 8.2.0 version.	table
Capitalize first character of generated headings	On	Enable this option to make table heading columns look better by capitalizing leading character of names generated as a result of Paths to fields to be included. Available from 6.5 version.	capitalize
Show non-formatted version of generated wiki	Off	Enable this option 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.	showWiki
Escape special characters in wiki	Off	Enable this option to allow few special characters to be escaped so that the formatting is unaffected. When wiki output is requested (Output format is set to wiki), some special characters (like '\|', '[', ']', '{', '}') in data can cause undesirable formatting of the table. By default, data that has wiki markup is rendered correctly.	escape
Render wiki markup macros in body	Off	Enable this option to render wiki markup macros found in the body prior to processing as CSV. This is useful to run macros from apps such as Scripting for Confluence, Run CLI Actions in Confluence, SQL for Confluence, or similar, that can produce JSON output.	macros
Stop encoding of html characters	Off	Enable this option to display the HTML content such as links correctly for JSON tables with Output format as html. By default, HTML content like <a href=http://google.com>google> displays as text. Your administrator must grant specific users or groups to use this capability using Macro Security for Confluence.	disableAntiXss

Augment parameters

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

Common parameters

The parameters listed on this page are a part of our common table capabilities that are available in many macros that produce or modify tables.

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

Examples

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)

Other macros

The list of all other macros available within this app is as follows:

Advanced Tables for Confluence

JSON Table macro - 8.x

On this page