The Table Excerpt/Table Excerpt Include macros combine different kinds of table excerption and multi-excerption in one tool:

  • You can reuse your tables multiple times within the same page and/or other pages across your Confluence instance.
    The macros improve the performance of pages storing large tables and let you use the referenced tables for any purpose including filtering, building multiple charts and pivot tables. As a result, you get a kind of a dashboard based on one source table (you update the original table and all the changes are passed to its referenced copies automatically)


  • You can build combined reports using excerpts from multiple pages and spaces searched by:
    • page names
    • page trees
    • labels

The Table Excerpt/Table Excerpt Include macros serve as an advanced version of the standard Page Properties/Page Properties Report and Excerpt/Excerpt Include macros (collect tables with multiple data rows, support dynamic tabular macros such as Jira Issues, and much more).

Inserting the Table Excerpt Macro

Adding the Table Excerpt macro to a page:

  1. In the Confluence editor, choose Insert > Other Macros.
  2. Find and select the required macro.
  3. Enter the unique identifier (name) for the macro.
  4. Click Insert.

Speeding up macro entry with autocomplete: type / on Cloud or { on Data Center and the beginning of the macro name "Table Excerpt" to see a list of suggested macros. Select the Table Excerpt macro from the prompted results.

Adding a Table into the Table Excerpt Macro:

  1. Copy (cut) a table.
  2. Paste the table into the Table Excerpt macro placeholder.

Later you will be able to reference this table by inserting the Table Excerpt Include macro and entering the specified unique identifier (name) of the required Table Excerpt macro.

Inserting the Table Excerpt Include Macro

1. In the Confluence editor, choose Insert > Other Macros.

2. Find and select the required macro.

3. Specify the settings:

  • Enter the Excerpt name: specify the unique identifier (name) of the correspondent Table Excerpt macro. The table(s) that is(are) included into the Table Excerpt macro(s) with this name will be referenced.
  • Select the Excerpt source to define where the macro should look for the correspondent Table Excerpt macros:
    • Current page
    • Specific page (specify the page title)
    • Page and child pages (specify the page title)
    • Page and all descendants (specify the page title)
    • Pages with labels (specify the page labels and the space title)
  • If you select the Current page option, select the  Show a copy of the source table checkbox in case you want to show a copy of a source table in the page view mode.
  • If you select other options, choose to Show page meta data in case you want to include such meta information as:
    • Source page title
    • Parent page title
    • Space title
    • Space key
    • Labels
    • Source page excerpt (abstract)
    • Author
    • Last modifier
    • Created
    • Updated
    • Page version
    • Page ID
  • To improve performance of the page, select the Output cached results checkbox. Please note that in this case the included content is static. To update the content in the Table Excerpt Include macro, you need to visit the source page. If the checkbox is unchecked, the included content is dynamic, i.e. the latest edition of the source content will be displayed in Table Excerpt Include.

4. Click Insert.

You can use the Table Excerpt Include macro within one page without showing the source table in combination with the Pivot Table and Chart from Table macros because a pivot table and a chart can be built without displaying a source table.

On the other hand, if you want to use the Table Excerpt Include macro within one page in combination with the Table Filter macro you need to select the "Show a copy of the source table" checkbox because this macro requires a table for its correct work.

Note that after changing page permissions for a user, viewing the restricted data in the Table Excerpt Include macro is still possible using the Output cached results option until this user or another with the same restrictions revisit the page.

The reason for this is that the user has already viewed or exported restricted data on the page earlier.

Creating a Dashboard: Reusing the Same Table for Generating Multiple Charts

  1. Insert the Table Excerpt macro and name it. Place the source table into the macro body according to the instructions above.
  2. Insert the Table Excerpt Include macro as many times as you need (specify the name of your excerpt and choose the Current page option as the Excerpt source) and place it into the Table Filter, Pivot Table or/and Chart from Table macros. 
  3. Adjust the required macro parameters for filtration, aggregation, and visualization.
  4. Save the page.

If you need to create a deep macro sequence on Cloud (we mean not a simple one like Pivot Table > Table Excerpt Include but with two or more macros with bodies like Chart from Table > Pivot Table > Table Excerpt Include), insert the Table Toolbox macro.

You'll be able to put the Table Excerpt Include macro in the Table Toolbox macro placeholder, then go to the Table Toolbox macro settings and nest the required macros there. The Table Toolbox macro is specifically designed to overcome the new Cloud editor limitations.

As a result, you'll get multiple charts (pivot tables, filter views) based on the same source table. And you'll need to update only this original table (all the changes are passed to the referenced copies automatically).

Generating a Combined Report: Collecting Tables from Multiple Pages

If you need to build a report from tables that have the same column names but come from different pages, please do the following steps:

1. Wrap tables that you want to collect in the Table Excerpt macros. Name these excerpts identically.
2. Insert the Table Excerpt Include macro on the page where you want to generate a report.
3. Specify the settings: 

  • Excerpt name: type in the name of your excerpts
  • Excerpt source: define where to look for the pages containing the Table Excerpt macros

4. Enable the Show as a report table option.
5. Save the page to see the result.

Note that if your tables have different column names, you need to use the Table Transformer macro to merge all the collected tables into one big table.

Other Handy Settings of the Table Excerpt Include Macro

Transposing Tables

You can transpose your source table(s) using the corresponding option in the Table Excerpt Include macro browser:

  • Auto - tables are transposed only in case they can be merged into one table with a header row. This option works only if Show as a report table is enabled.
  • Always - tables are transposed in any case.
  • Never - tables are not transposed.

For more thorough description with screenshots, please visit the "Comparison with native Page Properties Report/Excerpt Include macros" page.

Showing Page Metadata

To depict page metadata, please do the following:

  1. Open the settings of the Table Excerpt Include macro.
  2. Specify the settings for the Show page meta data field.
  3. Save the page to see the result.

Deriving Table Excerpts from Different Spaces

To extract Table Excerpt(s) from other space:

  1. Add Table Excerpt Include to a page.
  2. Open the settings of the Table Excerpt Include macro.
  3. Specify the Excerpt source.

  4. Fill in the Page title field by either starting to enter the page name to select it from the appearing dropdown OR manually via the following pattern:

    Space key:Page title -> e.g. NK:MY PAGE
    CODE
  5. Save the macro and the page.

In general, indicating&selecting the page name from a different space in the Page Title field automatically determines its location: if you have several pages with the same title in the list, you'll see the space name in the hint while hovering your mouse cursor near the page names.

But the manual entering of the Space Key may be used to derive Table Excerpt(s) from other spaces as well.

In case you wonder how to locate your space key for further indication in the macro, it can be found the following ways:
- Via Confluence Space Tools→Overview→Space Key
- In the URL of the source page containing Table Excerpt after publishing it (e.g. https://Your_Confluence_Site_Name/display/SPACE KEY/Page title)

How the Location of Table Excerpt within the Macro Sequence Affects the Result

Table Filter > Table Excerpt > Table

Let's discuss the first macro sequence: Table Filter > Table Excerpt > Table. As the Table Excerpt macro is placed between the source table and the Table Filter macro, only the original table without filters will be reused.

Table Excerpt > Table Filter > Table

And here is the second macro sequence to compare: Table Excerpt > Table Filter > Table. As the Table Excerpt macro is placed on top of the Table Filter macro, you will reuse the already filtered original table. 

So, by choosing the place of your Table Excerpt macros, you can choose what content you need to reuse (original table, filtered table, aggregated table, visualized table, and so on).

Please note that for such cases on Confluence Cloud the Table Excerpt macro is also placed within the Table Toolbox macro shell (you can easily drag'n'drop it there).