---
title: "JSON Table Macro"
canonical: "https://support.appfire.com/space/TBL/74815257/JSON%20Table%20Macro"
format: markdown
---
> Macro (div)
> 
> ### On this page
> 
> > Macro (toc)

# 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. 

> Macro (excerpt)
> 
> 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 (Server only).
>   - From a Space Template (Server only).
>   - 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 [Common table capabilities](https://appfire.atlassian.net/wiki/spaces/info/pages/86082804).

> ✅ Available in plugin [release 6.3](https://appfire.atlassian.net/wiki/spaces/TBL/pages/74814293) and above.

> ⚠️ **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> <span style="color: #000000">Refer to this</span> [documentation](https://appfire.atlassian.net/wiki/spaces/CMSP/overview) <span style="color: #000000">to for more information on the </span>*<span style="color: #000000">Macro Security for Confluence </span>*<span style="color: #000000">app.</span>
> ⚠️ 
> ⚠️ <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>

# Basic Use

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

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

### Screenshot

![image](media://cc5aa511-4160-4d3b-80ed-d02f7b1d41d6)

# Parameters

:info:<span style="color: #000000"> Click a column heading to toggle the sorting of that column.</span>

> Macro (table-plus)
> 
> | **Parameter** | **Default** | **Macro Browser Label** | **Description** |
> | --- | --- | --- | --- |
> | **paths** | <required> | Paths to fields | <span style="color: #505050">Normally, specify a single path to generate a single table. </span><span style="color: #505050">Simple form is a dot separated list of field names to reach the specific field within the JSON string. Example: </span>**<span style="color: #505050">total.monthlies</span>**<span style="color: #505050">. </span><br><span style="color: #505050">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.</span><br><span style="color: #505050">Paths are expressed in </span>[<span style="color: #505050">JSONPath</span>](http://goessner.net/articles/JsonPath/)<span style="color: #505050"> syntax.</span> |
> | **fieldPaths** | all fields | Paths to fields to be included | <span style="color: #505050">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.</span><br>Example for the **issues** field from the [JIRA search REST API](https://docs.atlassian.com/jira/REST/latest/#d2e417):   
> **key, fields.summary, ****fields.issuetype.name****, ****fields.issuetype.id****, fields.fixVersions[*].name** |
> | **fieldOrderRegexPatterns** |  | Regex patterns for ordering fields | <span style="color: #505050">Comma separated list of </span>[<span style="color: #505050">regular expression (regex)</span>](https://appfire.atlassian.net/wiki/spaces/info/pages/86082100)<span style="color: #505050"> pattern</span><span style="color: #505050">s. </span><br><span style="color: #505050">This parameter is used only when defaulting </span>**<span style="color: #505050">fieldPaths </span>**<span style="color: #505050">to all fields; o</span><span style="color: #505050">therwise the order specified by </span>**<span style="color: #505050">fieldPaths</span>**<span style="color: #505050"> is used. </span><br><span style="color: #505050"> </span><span style="color: #505050">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: #505050">Note: A field found by an earlier pattern is ordered before fields not found or fields found by a later pattern.</span> |
> | **sortPaths** |  | Paths used to determine sort order | <span style="color: #505050">Comma separated list of path references to fields (simple only) to be used to determine how rows will be initially sorted. </span><br><span style="color: #505050">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. </span><span style="color: #505050">The sort direction is ascending unless the sortDescending is selected. </span><span style="color: #505050">This sorting is done before the HTML is generated for display.</span> |
> | **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'.<br>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.<br>- **^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.<br>Additional options available for Server only.<br>- **#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. :info: Special note: [How to deal with templates on Confluence 4.3 and later](https://appfire.atlassian.net/wiki/spaces/info/pages/86120194).
> - **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.<br>Example: **UTF-8**.<br>[More ...](http://en.wikipedia.org/wiki/Character_encoding) |
> | **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.<br>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.<br>This is useful to run macros from [Scripting for Confluence](https://appfire.atlassian.net/wiki/spaces/SCRP), [Run CLI Actions in Confluence](https://appfire.atlassian.net/wiki/spaces/CCLI), [SQL for Confluence](https://appfire.atlassian.net/wiki/spaces/SQL), 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**](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](https://appfire.atlassian.net/wiki/spaces/CMSP/overview). |

## Augment parameters

See [Augments](https://appfire.atlassian.net/wiki/spaces/TBL/pages/74814982) for details for modifying column headings and column data.

## Common parameters

> Macro (include)

# Examples

> Macro (contentbylabel)

# Compatibility

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

# Other Macros

<span style="color: #000000">Below is a list of all other Macros available within this Add-on:</span>

> Macro (contentbylabel)

# Additional References

- [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/TBL/pages/74814982)
- [Common table capabilities](https://appfire.atlassian.net/wiki/spaces/info/pages/86082804)
- [Scripting for Confluence](https://appfire.atlassian.net/wiki/spaces/SCRP)
- [Run CLI Actions in Confluence](https://appfire.atlassian.net/wiki/spaces/CCLI)
- [SQL for Confluence](https://appfire.atlassian.net/wiki/spaces/SQL)
- [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)
- [How to deal with templates on Confluence 4.3 and later](https://appfire.atlassian.net/wiki/spaces/info/pages/86120194)