RFC-142: Confluence Migration Content Index for Macros

General Request for Comments (RFC)
, , ,
1

RFCs are a way for Atlassian to share what we’re working on with our valued developer community.

It’s a document for building shared understanding of a topic. It expresses a technical solution, but can also communicate how it should be built or even document standards. The most important aspect of an RFC is that a written specification facilitates feedback and drives consensus. It is not a tool for approving or committing to ideas, but more so a collaborative practice to shape an idea and to find serious flaws early.

Please respect our community guidelines: keep it welcoming and safe by commenting on the idea not the people (especially the author); keep it tidy by keeping on topic; empower the community by keeping comments constructive. Thanks!

Project Summary

We propose providing an export of a content index referenced by macro names to Apps during Confluence migrations to help them identify which pages or blog posts require macro transformations without querying every page.

  • Publish: 10 August 2026

  • Discuss: 24 August 2026

  • Resolve: 7 September 2026

Problem

During Confluence migrations, Apps often need to transform the macros found on migrated pages and blog posts. Their macros are stored in the pages and blog posts and due to that, Apps had no way to retrieve which pages had macros they were interested in.

Because of this, Apps during migration currently resort to querying every page on the migrated Confluence instance to perform their required transformation. Depending on the number of pages migrated, this can cause a significant delay (due to request volume an rate-limiting) in processing a migration.

If there was a way of retrieving references to the pages and blog posts a specific macro exists on, it would reduce the amount of requests an App would need to perform its required transformations. This would reduce migration time for the customer.

Proposed Solution

We are considering having apps declare what macros they are interested in knowing the page and blog post references for in their MigrationListener App migration platform via the ConfluenceAppCloudMigrationListenerV1 interface similar to P2 to Forge Macros .

public class ConfluenceAppMigListener implements DiscoverableForgeListener, ConfluenceAppCloudMigrationListenerV1 {
  ...  
  @Override
    public Map<String, String> getMacrosToIndex() {
        return new HashSet<>(Set.of("macroname-1","macroname-2"));
    }
}
public interface ConfluenceAppCloudMigrationListenerV1 {
    ...
    default Set<String> getMacrosToIndex() {
        return new HashSet<>();
    }
}

The proposed approach involves indexing pages and blog posts by the macros declared on an App’s ConfluenceAppCloudMigrationListenerV1. The export of the proposed index can be retrieved (via a public presigned url) by the App to utilise during the app’s migration.

The propose format for that index export is:

export.ndjson

{"macroname": "macroname-1", "contentIds": ["2001", "2002", "2003",...]}
{"macroname": "macroname-1", "contentIds": ["3004", "3005", "3006"....]}
{"macroname": "macroname-1", "contentIds": ["4007", "4008", "4009"]}
{"macroname": "macroname-2", "contentIds": ["2011", "2012", "2013"]}
{"macroname": "macroname-2", "contentIds": ["2014", "2015", "2018"]}

The contentIds array may contain 0-1000 items

The same macroname can appear on multiple lines but will be next to each other

macroname that aren’t declared by the App may appear in the index, it is expected that the App disregards those entries.

Asks

While we would appreciate any reactions you have to this RFC (even if it’s simply giving it a supportive “Agree, no serious flaws”), we’re especially interested in learning more about:

  1. What do you think about the format of the index file?

  2. What do you think about declaring the macros in the migration listener?

    1. What do you think about declaring the macros in the Forge app’s manifest?

  3. What would your App do during migration if it knew which pages and blog posts macros were on?

  4. When does your App need to know the pages and blog posts a macro is on?

  5. Are there other ways this may impact that we haven’t anticipated?

1 Like