Confluence macro indexing speeds up macro transformation during app migration. Your cloud app can request an index file listing where its macros appear in the migrated content, so it doesn't have to query Confluence pages to find them.

Can my app use this?

Yes, if you can answer yes to all of these questions:

Question	Reasoning
Does your app support Confluence?	This feature only applies to Confluence Data Center to Cloud app migrations.
Is your cloud app built on Forge or Forge Remote?	Both are supported. Pure Connect apps are not supported.
Does your app have an automated migration path?	Your app must use the app migration platform through the Confluence Cloud Migration Assistant (CCMA).
Does your Data Center app define macros?	This feature only impacts Confluence macros.
Does your cloud app need to update those macros or process their content?	This feature is only relevant to apps that transform Confluence macros as part of their app migration.

How to use this feature

1. Declare your macros

Add migration:macrosToIndex to the modules section of your cloud app's Forge manifest:

1
2
3
4
5
6
7
modules:
  migration:macrosToIndex:
    - key: macros-to-index
      macros:
        - new-diagram
        - chart

Field	Value
`key`	A module key you choose, such as `macros-to-index`.
`macros`	A list of macro names to index. Use the macro names that exist in cloud after migration. For example, if your migration maps the server macro `diagram` to `new-diagram` on the cloud, declare `new-diagram`. Note: Do not include the Forge app ID or environment ID prefix in this declaration. That is, do not use the form `{appId}/{environmentId}/static/{name}`.

Deploy the manifest change and install that version on the destination site.

2. Retrieve the index during an app migration

Your app can request the indexing during its app migration. The index is ready to be requested after your cloud app receives its listener-triggered event. Your cloud app can use the transferId associated with the migration to request the index.

Forge Native

Upgrade your @forge/migrations package to at least version 3.2.0. The sdk provides two new methods to request the index.

getConfluenceMacroIndexUrl

1
2
3
4
5
6
7
import { migration } from '@forge/migrations';

const { url } = await migration.getConfluenceMacroIndexUrl(transferId);
const response = await fetch(url, {headers: { "Range": "bytes=0-100000" }});
const index = await response.text();

The response contains a presigned url valid for 1 hour. You can use this url to download the index file. A new url with a new 1 hour validity will be returned if getConfluenceMacroIndexUrl is called again. The request to the presigned url can include Range headers to download a specific range of bytes from the index file, this can be used to manage memory usage by your app in the forge function.

getConfluenceMacroIndexIterator

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
interface ConfluenceMacroIndexRow {
    macroname: string;
    contentIds: string[];
}

import { migration } from '@forge/migrations';

let rowIndex = 0;

const iterator = migration.getConfluenceMacroIndexIterator(transferId, {rowIndex: rowIndex});
for await (const rowData of iterator) {

   const row: ConfluenceMacroIndexRow = rowData as ConfluenceMacroIndexRow;
   rowIndex++;
}

The getConfluenceMacroIndexIterator returns a row of the index file for each iteration. The rowIndex parameter can be used to resume the iteration from a specific row.

getConfluenceMacroIndexUrl will require you enable egress traffic for your Forge app to the domain https://app-migration-service.services.atlassian.com/public/storage/ in your Forge app's manifest. This will impact your app's Runs on Atlassian status, if this is undesirable, it is recommended to use getConfluenceMacroIndexIterator.

Forge Remote

Submit a POST request to the following endpoint with no body. For authentication refer to Calling Atlassian APIs from a Forge remote: https://api.atlassian.com/app/migration/forge/v1/confluenceMacroIndex/{transferId}

Response:

1
2
3
4
{
  "url": "https://app-migration-service.services.atlassian.com/public/storage/XXX"
}

The response contains a presigned url valid for 1 hour. You can use this url to download the index file. A new url with a new 1 hour validity will be returned if endpoint is called again. The request to the presigned url can include Range headers to download a specific range of bytes from the index file, this can be used to manage memory usage by your app.

Connect-on-Forge

Please contact us for further details.

3. Use the index

The index file is newline-delimited JSON, such as the following:

1
2
3
4
5
{"macroname":"5b16954a-7182-4f38-bc02-9ff11a7a28e8/d43f055b-43d9-482a-874a-7bc97df5311e/static/new-diagram","contentIds":["2001","2002"]}
{"macroname":"5b16954a-7182-4f38-bc02-9ff11a7a28e8/d43f055b-43d9-482a-874a-7bc97df5311e/static/new-diagram","contentIds":["2003"]}
{"macroname":"5b16954a-7182-4f38-bc02-9ff11a7a28e8/d43f055b-43d9-482a-874a-7bc97df5311e/static/chart","contentIds":["2002","2004"]}
{"macroname":"non-declared-macro","contentIds":["2002","2004"]}

Field	Type	Description
`macroname`	`string`	The macro name in the cloud app. If declared to be forge migratable they will be in its Forge app qualified form: `{appId}/{environmentId}/static/{name}`
`contentIds`	`array of strings`	Cloud IDs of the pages or blog posts containing that macro with up to 1000 IDs per row.

The same macroname can appear on multiple lines but will be adjacent in the file.
If none of the migrated pages contain a declared macro, the index file is empty.
Apps with no declared macros do not generate an index file.
The list of contentIds returned for a given macroname will contain all the contentIds for the pages migrated in the spaces for the migration. For technical reasons the contentIds may contain pages which do not contain the macro, your code should handle this case.