Macro

The macro module inserts dynamic content into the user interface via an editor. Editor macros are only compatible with the Atlassian editor. All cloud sites use the Atlassian editor by default.

The macro module works in Confluence, where the macro is inserted by typing / and selecting from the quick insert menu of the editor. The macro module is implemented by a Forge function.

Manifest structure

1
2
modules {}
└─ macro []
   ├─ key (string) [Mandatory]
   ├─ resource (string) [Mandatory]
   ├─ render (string) [Optional]
   ├─ resolver {} [Optional]
   ├─ viewportSize (string) [Optional]
   ├─ title (string | i18n) [Mandatory]
   ├─ icon (string) [Optional]
   ├─ categories (string[]) [Optional]
   ├─ unlicesedAccess (List<string>) [Optional]
   ├─ description (string | i18n) [Optional]
   ├─ hidden (boolean) [Optional]
   └─ config (boolean | {} | config object) [Optional]
     ├─ icon (string) [Optional]
     ├─ title (string | i18n) [Optional]
     ├─ resource (string) [Mandatory]
     ├─ render (string) [Optional]
     ├─ viewportSize (string) [Optional]
     ├─ openOnInsert (boolean) [Optional]
     └─ parameters [] [Optional]
        ├─ identifier (string) [Mandatory]
        ├─ type (string) [Mandatory]
        └─ indexing {} [Optional]
           └─ enabled (boolean) [Optional]
   ├─ adfExport {} [Optional]
   ├─ layout (string) [Optional]
   └─ autoConvert [] [Optional]
     └─ matchers [] [Mandatory]
        └─ pattern (string) [Mandatory]

resources []
├─ key (string) [Mandatory]
└─ path (string) [Mandatory]

Properties

i18n object

Dynamic module (Preview)

This module can also be declared as a dynamic module. However, this capability is currently available as a Forge preview feature.

For more details, see Dynamic Modules.

When you register a dynamic macro module, the data object uses the same properties as a static macro module in the manifest. The module key is generated server-side and returned in the create response; for updates, supply it in the URL path.

Code examples

The following examples show Dynamic Module implementations specific to this module. For more detailed information about the API used in these examples (including error handling information), see Dynamic Modules API.

Create a dynamic macro module

1
2
import { asApp } from "@forge/api";
const payload = {
  "type": "macro",
  "data": {
    "resolver": {
      "function": "resolver"
    },
    "resource": "main",
    "render": "native",
    "title": "Dynamic macro",
    "description": "A macro registered with the Dynamic Modules API",
    "autoConvert": {
      "matchers": [
        {
          "pattern": "https://www.example.com/*/about"
        }
      ]
    }
  }
}
const response = await asApp().requestAtlassian(`/forge/installation/v2/dynamic/module/`, {
  headers: {
    'Content-Type': 'application/json'
  },
  method: 'POST',
  body: JSON.stringify(payload),
});
const body = await response.text();
console.log(`Response: ${response.status} ${body}`);

Update a dynamic macro module

1
2
import { asApp } from "@forge/api";
const key = "macro-dynamic";
const payload = {
  "type": "macro",
  "data": {
    "resolver": {
      "function": "resolver"
    },
    "resource": "main",
    "render": "native",
    "title": "Updated dynamic macro",
    "description": "A macro updated with the Dynamic Modules API",
    "autoConvert": {
      "matchers": [
        {
          "pattern": "https://www.example.com/*/about"
        },
        {
          "pattern": "https://www.example.com/*/music"
        }
      ]
    }
  }
}
const response = await asApp().requestAtlassian(`/forge/installation/v2/dynamic/module/${key}`, {
  headers: {
    'Content-Type': 'application/json'
  },
  method: 'PUT',
  body: JSON.stringify(payload)
});
const body = await response.text();
console.log(`Response: ${response.status} ${body}`);

Extension context

UI Kit and Custom UI

Macro autoconvert

Macro autoconvert allows your app to automatically insert a macro into the editor when a user pastes a recognized URL. This is achieved by defining URL patterns in the manifest using the matchers property. These matchersare registered in the editor when the app is installed.

Example

1
2
modules:
  macro:
    - key: autoconvert-app
      resource: main
      render: native
      resolver:
        function: resolver
      title: Forge app for autoconvert
      description: Example for autoconvert manifest
      autoConvert:
        matchers:
          - pattern: https://www.example.com/*/about
          - pattern: https://www.example.com/*/music
          - pattern: https://*.example.com/*/movies/*
          - pattern: https://example.com/gifs/*/
          - pattern: http://*.example.com/media/*/.gif
          - pattern: customScheme://example:custom
          - pattern: customScheme:example:*
  function:
    - key: resolver
      handler: index.handler
resources:
  - key: main
    path: src/frontend/index.jsx
app:
  id: "<your app id>"

The URL patterns use wildcards to match parts of the URL that can vary, such as unique IDs. Wildcards are defined using *.

Use a new * for each segment in the URL you want a wildcard for. For example, https://www.example.com/* will match https://www.example.com/about but will not match https://www.example.com/about/contact. To match this path as well you need to include https://www.example.com/*/* as one of your matchers.

You'll need to define a separate matcher for each relevant internet protocol, such as http and https.

Creating custom URL schemes is also supported. For example, customScheme:* can be used to match any URL that starts with that custom scheme such as customScheme://example:custom. Any custom schemes will have to be registered on the system they will be used on, such as iOS, Windows or Android. Either :// or just : can be used as the initial separator in the URL scheme then : thereon.

Example patterns

Wildcard path

1
2
- "pattern": "https://www.example.com/*/about"

Wildcard in subdomain

1
2
- "pattern": "https://www.*.example.com/help"

Matching wildcard paths

1
2
- "pattern": "https://bitbucket.org/*/*/*"

Matching custom URL schemes

1
2
- "pattern": "customScheme:example:custom"
- "pattern": "customScheme://example:custom"

Matching custom URL scheme wildcard

1
2
- "pattern": "customScheme:example:*"
- "pattern": "customScheme://example:*"

When a pasted URL matches a defined pattern, the macro is created in the editor, and the URL is captured and inserted as a parameter into the macro body. This parameter can be accessed using the autoConvertLink property.

Macro custom configuration

Extension context in the macro editor

There are two additional extension context parameters available when you are in macro configuration editor context.

Config parameter types and value formats

Each entry in config.parameters declares a type that determines how Confluence stores the value and what format your app receives.

Values are always returned from useConfig() (and must be sent to view.submit()) as strings. For confluence-content (single and multiple) and all multi-value parameters, the string is a stringified JSON object or array that follows a special format described in the table below. For single attachment and spacekey values, the string is the raw filename or space key and does not need to be parsed.

Using confluence-content, attachment, or spacekey stores the value as a structured Confluence reference (rather than plain text), which lets Confluence automatically update the reference if the linked content is renamed or moved.

For example, this macro declares three config parameters, each with a unique identifier and a type:

1
2
modules:
  macro:
    - key: my-macro
      resource: main
      render: native
      resolver:
        function: resolver
      title: My Macro
      config:
        resource: config
        render: native
        parameters:
          - identifier: message
            type: string
          - identifier: targetPage
            type: confluence-content
          - identifier: relatedSpaces
            type: spacekey

The identifier you choose is the key you use to read the value back from useConfig():

1
2
import { useConfig } from "@forge/react";

const config = useConfig();
const message = config.message; // value of the "message" parameter

confluence-content object reference

Each confluence-content value (single, or each item in a multiple array) is a JSON object with the following fields:

Example of a page reference (same space):

1
2
{ "content-title": "hello world" }

Example of a page reference in another space:

1
2
{ "content-title": "hello world", "space-key": "OTHER" }

Example of a blog post reference:

1
2
{
  "content-title": "my blog",
  "posting-day": "2026/04/27",
  "space-key": "OTHER"
}

For any value stored as JSON (all confluence-content values, and any multi-value parameter), parse the string before using it:

1
2
import { useConfig } from "@forge/react";

const config = useConfig();
// e.g. a `confluence-content` parameter named "targetPage"
const targetPage = JSON.parse(config.targetPage);
// { "content-title": "hello world", "space-key": "OTHER" }

Conversely, when you set one of these JSON-valued typed parameters (any confluence-content value, or any multi-value parameter), build the object (or array) and serialize it with JSON.stringify() before passing it to view.submit(). The value must be sent as a string:

1
2
import { view } from "@forge/bridge";

// e.g. a `confluence-content` parameter named "targetPage"
const targetPage = { "content-title": "hello world", "space-key": "OTHER" };

view.submit({
  config: {
    targetPage: JSON.stringify(targetPage),
  },
});

Single attachment and spacekey values are the exception — send them as the raw filename or space key string, without JSON.stringify(). For plain (non-typed) config parameters, you can pass values in their native form (strings, numbers, booleans, objects, and arrays); see Supported config payload format.

Options for submitting the configuration

This table details the options supported by view.submit() in the context of custom macro configuration.

1
2
view.submit({
  config: {
    param1: "test",
    param2: [1, 2, 3]
  }
})

1
2
view.submit({
  config: {},
  body: {
    type: "doc",
    version: 1,
    content: [
      // ADF content
    ]
  }
})

1
2
view.submit({
  config: {},
  keepEditing: true
})

Supported config payload format

The config payload only supports values that can be serialised to JSON.

The following types are allowed on the payload:

1. undefined
2. string
3. number
4. boolean
5. object (can contain any of the allowed types, including nested objects)
6. array (can contain strings, numbers, booleans, and objects; all items in the array must be of the same type).

The following types are not allowed:

• Nested arrays (arrays as direct children of arrays)
• null
• Any data types that are not serializable to JSON (e.g. Map, Set, etc.)

If you want greater control over the storage format of your configuration, such as being able to store nested arrays and nulls, we recommend serializing your configuration to JSON upfront, and storing it as a string.

Error code guide

This table details the possible error codes that may be thrown by view.submit():

Notes on layout and sizing

Inline macro width (Custom UI)

Custom UI inline macros are rendered inside an <iframe>. All major browsers apply a default minimum width of 300px to <iframe> elements, which means your inline macro will render at a minimum of approximately 300px wide even if the content inside is smaller.

To override this and allow the macro to shrink to fit its content, add the following CSS to your Custom UI app. The recommended approach is to add it in a <style> tag or an external stylesheet in your index.html:

1
2
<style>
  body {
    width: fit-content;
  }
</style>

This tells the browser to size the body to its content rather than expanding to the iframe default width. The fit-content value is supported across all browsers that Forge targets.

1
2
permissions:
  content:
    styles:
      - "unsafe-inline"

Tutorials

Add configuration to a macro with UI Kit

The app allows you to customize what the macro displays by adjusting settings in a form.

Start tutorial

Add custom configuration to a macro

The app’s configuration can be edited using a custom configuration modal.

Start tutorial

Using rich-text bodied macros

How to configure the manifest and render rich text body content.

Start tutorial