Last updatedNov 21, 2019

Dynamic modules

In addition to declaring modules in the app descriptor, Connect apps can register certain types of modules dynamically at runtime. The ability to dynamically register modules provides for flexibility in defining an app's behavior and is useful for creating highly configurable apps that extend Confluence in response to arbitrary user needs.

Modules are registered dynamically in the context of an app installation, which means that an app can register different modules for each Confluence tenant. By contrast, an app's statically registered modules are the same in all tenancies.

Apps manage modules for a tenant dynamically by sending JWT-signed requests to a REST resource to:

Lifecycle

During module registration, the app's translation files are available and used to resolve any i18n keys.

If an app is uninstalled and installed again, all of its registered modules are restored.

If a new version of the app defines modules statically that conflict with dynamically registered modules, all the app's dynamically registered modules are removed. This action enables the new version to be installed. An example of a conflict between a dynamically and statically registered module is where they use the same key.

Restrictions

Up to 10 modules can be registered dynamically in a tenancy.

You can register the following module types dynamically:

Register modules dynamically

To register modules dynamically, call POST /rest/atlassian-connect/1/app/module/dynamic sending a JSON object containing the modules to register. The object's format is the same as the value of the modules property of the app descriptor. For example:

1
2
3
4
5
6
7
8
9
10
11
12
{
    "webItems": [
      {
        "key": "my-webitem",
        "location": "system.admin/globalsettings",
        "url": "/my-webitem",
        "name": {
          "value": "My Web Item"
        }
      }
    ]
}

This object registers a web item named My Web Item.

If one of the module definitions in a request has the same key as a statically or dynamically registered module or is invalid, none of the modules are registered. A module is invalid when it:

  • is missing required properties.
  • contains invalid property values. For example, numbers out of range or a string outside an allowed set.
  • is not compatible with the app configuration. For example, webhook modules require the app to have the "READ" scope.

See Register modules for more information.

Retrieve dynamically registered modules

Call GET /rest/atlassian-connect/1/app/module/dynamic to obtain a list of the calling app's registered modules. For example, for the module registered above this call returns:

1
2
3
4
5
6
7
8
9
10
11
12
{
    "webItems": [
      {
        "key": "my-webitem",
        "location": "system.admin/globalsettings",
        "url": "/my-webitem",
        "name": {
          "value": "My Web Item"
        }
      }
    ]
}

See Get modules for more information.

Remove dynamically registered modules

To remove all of an app's dynamically registered modules, call DELETE /rest/atlassian-connect/1/app/module/dynamic. To remove a module, define the key in the moduleKey query parameter. You can specify the parameter multiple times to remove more than one module, for example:

DELETE /rest/atlassian-connect/1/app/module/dynamic?moduleKey=module1&moduleKey=module2

See Remove modules for more information.