MultiExcerpt Include - Server across spaces not working after upgrade or copy/move


See KB article here: MultiExcerpt Include - Server across spaces not working after copy/move

The symptom of this problem is that ME-Include does not work across spaces. It cannot find the ME that is in another space. The broken page may have been copied or moved from its original location or ME may have been upgraded from an old version (circa 5.2.x) to a more modern version.

In this case there is no "SpaceWithExcerpt" parameter in the ME-Include macro, only a "PageWithExcerpt" parameter (visible by viewing the Storage Format markup of the page). In an old version of the ME plugin there were problems with ME Includes across spaces. That problem was fixed in a way that broke some old ME-Includes that did not have a "SpaceWithExcerpt" parameter: when those ME-Includes are on pages that are copied or moved their “PageWithExcerpt” parameter gets damaged.

The broken ME-Includes only had a "PageWithExcerpt" parameter before they were copied/moved and it was for an include of an ME in another space. That "PageWithExcerpt" parameter had the key of the other space prepended to the page name like "TS:My Test Page". After a move or copy the “PageWithExcerpt” parameter may be corrupted by prepending the new location’s space key to the original value like “TS2:TS:My Test Page”, breaking the include because there is no page “TS:My Test Page” in the space TS2.

To solve the problem you can do this to the original pages and to any moved/copied pages that are broken: add a “SpaceWithExcerpt” parameter and repair the “PageWithExcerpt” parameter. This can be done automatically by editing the ME-Include macro in the macro editor:

  • open the page in edit mode (the page with the ME-Include that includes an ME from another space)

  • open the ME-Include in edit mode

  • populate the "Space With Excerpt" input with the space that the ME lives in, this sets the “SpaceWithExcerpt” macro parameter

  • verify that the "Page With Excerpt" is just a page name, not a space key prepended with ":" to a page name, this repairs the “PageWithExcerpt” macro parameter

  • save the macro, publish the page

The goal of the workaround is to populate <ac:parameter ac:name="SpaceWithExcerpt"> for the macro (visible by viewing the Storage Format of the page)

ME-Include in 5.2.8 and earlier:

ME-Include in new versions:

The difference is the addition of the SpaceWithExcerpt parameter.

If you were editing Storage Format you would find all "multiexcerpt-include" macros with a "PageWithExcerpt" parameter with a ri:page element that has a ri:space-key attribute. You would add a "SpaceWithExcerpt parameter with an ri:space element that has its ri:space-key set to the one in the page element.

Atlassian has a free app for editing Storage Format markup, Confluence Source Editor:

Here is a shell script that can be used to find all old ME-Includes that include excerpts from another space.

This script uses the jq command-line JSON parser and python so you will need to ensure you have those available in your shell.

This is a bash shell script that I have been running on a Mac.

Before you use the script make sure you can execute both jq and python in your shell. If you are not familiar with using the shell to run scripts like this then we can help with that.

This script requires you to edit it to set the BASE_URL to your Confluence server's base URL, seen in your admin config tools under General Configuration, Server Base URL.

This script invokes the Confluence REST API for content search, with 50 results per "page" of results, and iterates through that until all pages of results have been found.

The script then reformats the JSON results so they are more readable and more easily processed, by using python's mjson.tool

The JSON result files (0.json, 50.json, 100.json, etc) are combined into one big text file: search_results.txt.

Then you can find the IDs of the pages that have ME-Includes with "<ri:page ri:space-key=" in them using grep like this:

The "-A 6" switch tells the grep to include the line of text where the match is and the next 6 lines, which is just enough to show the "id" property of the found page:

Those found pages are the pages that have ME-Includes on them that are for an ME that is in a different space. Those are the ones you will want to edit to set the "SpaceWithExcerpt" parameter, either manually using the page editor and macro editor UI or by directly editing the Storage Format markup to add a macro parameter to the multiexcerpt-include macro like:

In the context of the macro definition, it looks like this:

Here is the script, you can create a file named something like in an empty directory on your filesystem on a machine that can make an HTTP/HTTPS request to your Confluence server to invoke the REST API. Don't forget to make it an executable file, using "chmod 777" or similar.

Freshdesk Tickets


Create a Support Ticket




Ture Hoefner