Last updated Jul 12, 2024

Macro autoconvert with Confluence Connect

DescriptionAdd autoconvert patterns to your macro experience.


Estimated time15 minutes


Ensure you have worked through the Getting started tutorial.

Macro magic

Macros are arguably the most powerful capabilities provided by the Confluence Editor. As an app developer, building a macro is a quick process, as outlined in our Getting started tutorial. However, Confluence Connect macros come bundled with extra behaviors and customizations - ensuring you are able to develop and guide users through the app experience you desire.

Let's take a quick look at macro autoconvert — a feature which allows for intelligent insertion of macros to the Confluence Editor (below is also a sneak peak of the Macro Custom Editor with Confluence Connect).  

macro autoconvert giphy

So, what happened here?

Autoconvert: We pasted the link,, into our Confluence page, and it auto-created an instance of the GIPHY macro, with this URL set.   

As a developer, this gives you extra control over the behavior of the macros you introduce into Confluence. Pretty awesome, right? Let's take a look at how to do this. ** **

If you haven't already built a basic GIPHY macro, check out the [Getting started tutorial](/cloud/confluence/getting-started)! It'll only take you a few minutes!

From URL to macro

Autoconvert works in a simple but powerful way.

By declaring URL patterns in our atlassian-connect.json descriptor, Confluence ensures that any pasted URLs which match these patterns are autoconverted to an instance of our macro, with a specific parameter set. This occurs by registering specific "matchers" in our macro module descriptor.

For example, if we specify a pattern of and relate this to the url parameter of our GIPHY macro, all pasted URLs which match this pattern will be converted to an instance of our GIPHY macro with the url set to{}.

"**{}**" denotes a wildcard pattern match. This allows the above pattern to match both of these urls:

If we were to for example, have a URL like{}/, this would match:

You can use as many wildcards in the same pattern, allowing for some complex URL matching!

The magic happens in our app descriptor. Add the following to the GIPHY module defined under 'dynamicContentMacros': 

  "autoconvert": {
    "urlParameter": "url",
    "matchers": [
        "pattern": "{}"

The key to remember here is, if we are specifying that the "urlParameter" is "url" as above, we must have a parameter with an "identifier" of "url" in our app descriptor.

For the above example we may have the following macro parameter defined: 

"parameters": [
    "identifier": "url",
    "name": {
      "value": "URL"
    "description": {
      "value": "Giphy URL."
    "type": "string",
    "required": true

We must also ensure that the rest of our macro parameters are not required (or in other words, have default parameter values), otherwise the macro editor will appear when a URL is pasted.

To see an example of more complex URL matching in play for GIPHY, check out the full atlassian-connect.json descriptor here!

Creating a macro through autoconvert

What more is involved here?

Nothing, that's it! Try pasting a link such as into your Confluence editor. You should see the following:   

this is pretty awesome giphy


Simple and awesome!

Rate this page: