---
title: "JSON Table macro - 8.x"
canonical: "https://support.appfire.com/space/atdc/2911505442/JSON%20Table%20macro%20-%208.x"
format: markdown
---
> Macro (aura-html)

# <span style="color: #000000">Overview</span>

<span style="color: #000000">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. </span>

<span style="color: #000000">The </span>*<span style="color: #000000">JSON Table</span>*<span style="color: #000000"> macro can import, format and display JSON (JavaScript Object Notation) data from anywhere, by:</span>

- <span style="color: #000000">Reading the JSON data from any of these sources:</span>
  - <span style="color: #000000">Within your Confluence page.</span>
  - <span style="color: #000000">From a file residing on the Confluence server.</span>
  - <span style="color: #000000">From a space template.</span>
  - <span style="color: #000000">From a page attachment.</span>
  - <span style="color: #000000">From an external URL.</span>
- <span style="color: #000000">Allowing customizable access to fields.</span>
- <span style="color: #000000">Supporting inclusion of Wiki Markup macros within the JSON data.</span>
- <span style="color: #000000">Combining with the </span>*<span style="color: #000000">Chart</span>*<span style="color: #000000"> macro to produce powerful data visualization.</span>
- <span style="color: #000000">Leveraging the same table styling capabilities as the </span>*<span style="color: #000000">Table Plus</span>*<span style="color: #000000"> macro.</span>

<span style="color: #000000">This macro supports certain</span> [Common table capabilities](https://appfire.atlassian.net/wiki/spaces/atdc/pages/2911505649)<span style="color: #000000">.</span>

> ✅ <span style="color: #000000">Available from</span> release 6.3 <span style="color: #000000">and above.</span>

> ⚠️ ### Applicable upto app version 8.1:
> ⚠️ 
> ⚠️ <span style="color: #000000">To enable using HTML content with JSON data, you must enable the </span>*<span style="color: #000000">Stop encoding of html characters</span>*<span style="color: #000000"> parameter. In such a case, it is recommended to contact your administrator to use </span>*<span style="color: #000000">Macro Security for Confluence</span>*<span style="color: #000000"> with this app to provide an additional layer of security to your data and privacy.</span> Refer to this [documentation](https://appfire.atlassian.net/wiki/spaces/CMSP) for more information on *Macro Security for Confluence *app.
> ⚠️ 
> ⚠️ <span style="color: #000000">From app version 8.2 onwards, if the </span>*<span style="color: #000000">Stop encoding of html characters</span>*<span style="color: #000000"> parameter is enabled, use of </span>*<span style="color: #000000">Macro Security for Confluence</span>*<span style="color: #000000"> is no longer needed as the macro itself provides additional security to your data.</span>

# <span style="color: #000000">Basic use</span>

<span style="color: #000000">This macro can be deployed using one of the following methods:</span>  


| <span style="color: #000000">Selected from the macro browser</span> | *<span style="color: #000000">Advanced Tables - JSON Table</span>* |
| --- | --- |
| <span style="color: #000000">Markup shortcut</span> | *<span style="color: #000000">{json-table}</span>* |

### <span style="color: #000000">Screenshot</span>

![Advanced Tables for Confluence Data Center JSON Table macro setup](media://f26e686c-4a75-499a-9a82-561ef01d9f93)

# <span style="color: #000000">Parameters</span>

### **<span style="color: #000000"><u>JSON settings</u></span>**

| Macro editor label | Default | Description | Macro parameter |
| --- | --- | --- | --- |
| **<span style="color: #000000"><u>Data source</u></span>** |
| <span style="color: #000000">Method of locating JSON data</span> | <span style="color: #000000">macro body</span> | <span style="color: #000000">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.</span><br>- **<span style="color: #000000">Attachment</span>**<span style="color: #000000"> - Data is read from the list of options selected for the following parameters:</span>
  - **<span style="color: #000000">Space</span>**<span style="color: #000000"> - Lists all available spaces.</span>
  - **<span style="color: #000000">Page </span>**<span style="color: #000000">- Lists all the pages available from the selected space.</span>  
<span style="color: #000000">The following options indicate:</span>
    - *<span style="color: #000000">@self</span>*<span style="color: #000000"> - current space or page</span>
    - *<span style="color: #000000">@home</span>*<span style="color: #000000"> - homepage of current space</span>
    - *<span style="color: #000000">@parent</span>*<span style="color: #000000"> - parent page of current page or space</span><br>> ⚠️ 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.<br>- 
  - **Attachment** - Lists all the attachments from the selected page.
- **<span style="color: #000000">Filename</span>**<span style="color: #000000"> - Data is read from the input specified in the </span>*<span style="color: #000000">File name</span>*<span style="color: #000000"> field. You can specify the file located in </span>***<span style="color: #000000">Confluence home directory/script/filename</span>***<span style="color: #000000">, also subdirectories.</span>
- **<span style="color: #000000">Template</span>**<span style="color: #000000"> - Data is read from a global page template specified in the </span>*<span style="color: #000000">Name of the template</span>*<span style="color: #000000"> field. </span><br>> ℹ️ Special note: [How to deal with templates on Confluence 4.3 and later](https://appfire.atlassian.net/wiki/x/AhciBQ).<br>- **URL**<span style="color: #000000"> - Data is read from the </span>*<span style="color: #000000">URL of JSON data</span>*<span style="color: #000000">, </span>*<span style="color: #000000">Username</span>*<span style="color: #000000">, </span>*<span style="color: #000000">Password</span>*<span style="color: #000000">, and </span>*<span style="color: #000000">Connection timeout</span>*<span style="color: #000000"> fields that are explained in the succeeding rows.</span>
- **<span style="color: #000000">Profile</span>**<span style="color: #000000"> - 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 (</span>*<span style="color: #000000">Profiles</span>*<span style="color: #000000">) and the URL (</span>*<span style="color: #000000">URL of CSV data</span>*<span style="color: #000000">) of the CSV file(s). Available from 8.1.0 version. </span><br>> ℹ️ - This option appears only if at least one profile exists in your instance.
> ℹ️ - For more information about profiles, refer to the [Configuration documentation](https://appfire.atlassian.net/wiki/spaces/atdc/pages/2911502499). | script |
| <span style="color: #000000">Profiles</span> |  | <span style="color: #000000">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 </span>*<span style="color: #000000">URL of JSON data</span>*<span style="color: #000000">.</span><br><span style="color: #000000">Appears if </span>*<span style="color: #000000">Method of locating CSV data</span>*<span style="color: #000000"> is set to </span>*<span style="color: #000000">Profile</span>*<span style="color: #000000">. Available from 8.1.0 version.</span> | <span style="color: #000000">profile</span> |
| <span style="color: #000000">URL of JSON data </span> |  | <span style="color: #000000">Enter the URL to a JSON file.</span> <span style="color: #000000">If a profile is specified the </span>*<span style="color: #000000">Profiles</span>*<span style="color: #000000"> 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.</span><br>> ℹ️ <span style="color: #000000">Use of this parameter may be restricted for security reasons. See your administrator for details.</span> | <span style="color: #000000">url</span> |
| <span style="color: #000000">Username (if required)</span> |  | <span style="color: #000000">Enter the user name to be used for URL access to JSON files.</span> | <span style="color: #000000">user</span> |
| <span style="color: #000000">Password (if required)</span> |  | <span style="color: #000000">Enter the user password to be used for URL access to JSON files. The </span>*<span style="color: #000000">Password </span>*<span style="color: #000000">is encrypted and remains secure (available from version 8.6.0).</span><br>> ⚠️ <span style="color: #000000">If the first attempt fails while decrypting the password, the</span>* JSON Table*<span style="color: #ff0000"> </span><span style="color: #000000">macro initiates three retry attempts to decrypt the password. (Available since app version 8.7.1.)</span> | <span style="color: #000000">password</span> |
| <span style="color: #000000">Connection timeout</span> |  | <span style="color: #000000">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.</span> | <span style="color: #000000">timeout</span> |
| <span style="color: #000000">File encoding</span> |  | <span style="color: #000000">Specify the encoding for an external file, if different from the system default handling. Example: </span>*<span style="color: #000000">UTF-8</span>*<span style="color: #000000">. Refer to </span>[<span style="color: #000000">this article</span>](http://en.wikipedia.org/wiki/Character_encoding)<span style="color: #000000"> for more information. Available from 4.1.0 version.</span> | <span style="color: #000000">encoding</span> |
| **<span style="color: #000000"><u>Data format</u></span>** |
| <span style="color: #000000">Paths to fields</span> | <span style="color: #000000"><required></span> | <span style="color: #000000">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: </span>*<span style="color: #000000">total.monthlies</span>*<span style="color: #000000">. </span><br><span style="color: #000000">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.</span><br><span style="color: #000000">Paths are expressed in</span><span style="color: #505050"> </span>[<span style="color: #505050">JSONPath</span>](http://goessner.net/articles/JsonPath/)<span style="color: #505050"> </span><span style="color: #000000">syntax.</span> | <span style="color: #000000">paths</span> |
| <span style="color: #000000">Paths to fields to be included</span> | <span style="color: #000000">all fields</span> | <span style="color: #000000">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.</span><br><span style="color: #000000">Example for the </span>*<span style="color: #000000">issues</span>*<span style="color: #000000"> field from the</span> [Jira search REST API](https://docs.atlassian.com/jira/REST/latest/#d2e417)<span style="color: #000000">:</span>   
*<span style="color: #000000">key, fields.summary, fields.issuetype.name,</span>*<span style="color: #000000"> </span>*<span style="color: #000000">fields.issuetype.id</span>*<span style="color: #000000">,</span>*<span style="color: #000000"> fields.fixVersions[*].name</span>* | fieldPaths |
| <span style="color: #000000">Regex patterns for ordering fields</span> |  | <span style="color: #000000">Enter a comma-separated list of</span><span style="color: #505050"> </span>[<span style="color: #505050">regular expression (regex)</span>](https://appfire.atlassian.net/wiki/x/NIIhBQ)<span style="color: #505050"> </span><span style="color: #000000">patterns. </span><br><span style="color: #000000">This parameter is used only when the </span>*<span style="color: #000000">Paths to fields to be included</span>*<span style="color: #000000"> field defaults to all fields; otherwise, the order specified in </span>*<span style="color: #000000">Paths to fields to be included</span>*<span style="color: #000000"> is used.</span><br><span style="color: #000000">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. </span><br>> ⚠️ <span style="color: #000000">A field found by an earlier pattern is ordered before fields not found or fields found by a later pattern.</span> | <span style="color: #000000">fieldOrderRegexPatterns</span> |
| <span style="color: #000000">Paths used to determine sort order</span> |  | <span style="color: #000000">Enter a comma-separated list of path references to fields (simple only) to be used to determine how rows are initially sorted. </span><br><span style="color: #000000">Paths are relative to the JSON field specified in the </span>*<span style="color: #000000">Paths to fields</span>*<span style="color: #000000"> 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 </span>*<span style="color: #000000">Sort descending</span>*<span style="color: #000000"> is selected. This sorting is done before the HTML is generated for display.</span> | <span style="color: #000000">sortPaths</span> |
| **<span style="color: #000000"><u>Data settings</u></span>** |
| <span style="color: #000000">Columns to display</span> |  | <span style="color: #000000">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.</span> | <span style="color: #000000">columns</span> |
| <span style="color: #000000">Output format</span> | *<span style="color: #000000">html</span>* | <span style="color: #000000">Specify how the output is formatted. The options are as follows:</span><br>- *<span style="color: #000000">html</span>*<span style="color: #000000"> - data is entered as standard HTML directly in the macro body.</span>
- *<span style="color: #000000">wiki</span>*<span style="color: #000000"> - data in the table rendered using the wiki renderer.</span> | <span style="color: #000000">output</span> |
| <span style="color: #000000">Strip leading qualifiers from generated headings</span> | <span style="color: #000000">Off</span> | <span style="color: #000000">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 </span>*<span style="color: #000000">Paths to fields to be included</span>*<span style="color: #000000">. For example, </span>*<span style="color: #000000">field.type</span>*<span style="color: #000000"> is converted to </span>*<span style="color: #000000">type</span>*<span style="color: #000000">. Available from 6.5 version.</span> | <span style="color: #000000">stripQualifiers</span> |
| <span style="color: #000000">Show result as table</span> | <span style="color: #000000">On</span> | <span style="color: #000000">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. </span> | <span style="color: #000000">table</span> |
| <span style="color: #000000">Capitalize first character of generated headings</span> | <span style="color: #000000">On</span> | <span style="color: #000000">Enable this option to make table heading columns look better by capitalizing leading character of names generated as a result of </span>*<span style="color: #000000">Paths to fields to be included</span>*<span style="color: #000000">. Available from 6.5 version.</span> | <span style="color: #000000">capitalize</span> |
| <span style="color: #000000">Show non-formatted version of generated wiki</span> | <span style="color: #000000">Off</span> | <span style="color: #000000">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.</span> | <span style="color: #000000">showWiki</span> |
| <span style="color: #000000">Escape special characters in wiki</span> | <span style="color: #000000">Off</span> | <span style="color: #000000">Enable this option to allow few special characters to be escaped so that the formatting is unaffected. When wiki output is requested (O</span>*<span style="color: #000000">utput format</span>*<span style="color: #000000"> is set to </span>*<span style="color: #000000">wiki</span>*<span style="color: #000000">), some special characters (like '</span>**|**<span style="color: #000000">', '</span>**[**<span style="color: #000000">', '</span>**]**<span style="color: #000000">', '</span>**{**<span style="color: #000000">', '</span>**}**<span style="color: #000000">') in data can cause undesirable formatting of the table. By default, data that has wiki markup is  rendered correctly.</span> | <span style="color: #000000">escape</span> |
| <span style="color: #000000">Render wiki markup macros in body</span> | <span style="color: #000000">Off</span> | <span style="color: #000000">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 </span>*<span style="color: #000000">Scripting for Confluence</span>*<span style="color: #000000">, </span>*<span style="color: #000000">Run CLI Actions in Confluence</span>*<span style="color: #000000">, </span>*<span style="color: #000000">SQL for Confluence</span>*<span style="color: #000000">, or similar, that can produce JSON output.</span> | <span style="color: #000000">macros</span> |
| <span style="color: #000000">Stop encoding of html characters</span> | <span style="color: #000000">Off</span> | <span style="color: #000000">Enable this option to display the HTML content such as links correctly for JSON tables with </span>*<span style="color: #000000">Output format</span>*<span style="color: #000000"> as </span>*<span style="color: #000000">html</span>*<span style="color: #000000">. By default, HTML content like </span>*<span style="color: #000000"><a href=http://google.com>google></span>*<span style="color: #000000"> displays as text. Your administrator must grant specific users or groups to use this capability using </span>*<span style="color: #000000">Macro Security for Confluence</span>*<span style="color: #000000">.</span> | <span style="color: #000000">disableAntiXss</span> |

## <span style="color: #000000">Augment parameters</span>

<span style="color: #000000">See</span> [Augments](https://appfire.atlassian.net/wiki/spaces/atdc/pages/2911506473) <span style="color: #000000">for details for modifying column headings and column data.</span>

## <span style="color: #000000">Common parameters</span>

> Macro (include)

# <span style="color: #000000">Examples</span>

> Macro (children)

# <span style="color: #000000">Compatibility</span>

- *<span style="color: #000000">Chart</span>*<span style="color: #000000"> macro - the </span>*<span style="color: #000000">JSON Table</span>*<span style="color: #000000"> macro can be used to create data for a chart</span>
- [Beanshell macro](https://appfire.atlassian.net/wiki/spaces/SCRP/pages/73728623) <span style="color: #000000">- can be used to generate </span>*<span style="color: #000000">JSON Table</span>*<span style="color: #000000"> macro and data as output from Java code (use </span>*<span style="color: #000000">output=wiki</span>*<span style="color: #000000">)</span>
- [Groovy macro](https://appfire.atlassian.net/wiki/spaces/SCRP/pages/73728611) <span style="color: #000000">- can be used to generate </span>*<span style="color: #000000">JSON Table</span>*<span style="color: #000000"> macro and data as output from Groovy code (use </span>*<span style="color: #000000">output=wiki</span>*<span style="color: #000000">)</span>
- [Jython macro](https://appfire.atlassian.net/wiki/spaces/SCRP/pages/73728662) <span style="color: #000000">- can be used to generate </span>*<span style="color: #000000">JSON Table</span>*<span style="color: #000000"> macro and data as output from Jython code (use </span>*<span style="color: #000000">output=wiki</span>*<span style="color: #000000">)</span>

# <span style="color: #000000">Other macros</span>

<span style="color: #000000">The list of all other macros available within this app is as follows:</span>

> Macro (children)

# <span style="color: #000000">Additional references</span>

- [JSON.org home](http://www.json.org/)
- [JSONPath](http://goessner.net/articles/JsonPath/)
- [JIRA REST API Example - Query issues](https://developer.atlassian.com/display/JIRADEV/JIRA+REST+API+Example+-+Query+issues)
- [Confluence Remote API Content examples](https://developer.atlassian.com/display/CONFDEV/Remote+API+Content+Examples)
- [Augments](https://appfire.atlassian.net/wiki/spaces/atdc/pages/2911506473)
- [Common table capabilities](https://appfire.atlassian.net/wiki/spaces/atdc/pages/2911505649)
- [Scripting for Confluence](https://appfire.atlassian.net/wiki/spaces/SCRP)
- [Run CLI Actions in Confluence](https://appfire.atlassian.net/wiki/spaces/CCLI)
- [Beanshell macro](https://appfire.atlassian.net/wiki/spaces/SCRP/pages/73728623)
- [Groovy macro](https://appfire.atlassian.net/wiki/spaces/SCRP/pages/73728611)
- [Jython macro](https://appfire.atlassian.net/wiki/spaces/SCRP/pages/73728662)