Dynamic Modules API (EAP)

You can manage Dynamic Modules through its REST API. This API checks every request for OAuth authorisation to determine if it has permissions to access the target installation.

No OAuth 2.0 scopes are required.

Remote compatibility

You can configure a remote backend to call the Dynamic Module REST API. See Calling Atlassian app APIs from a remote.

Remote backends can only use asApp calls for dynamic module operations; asUser calls are not allowed. This means your remote backend will only be able to call the Dynamic Modules API as a generic bot user.

requestAtlassian

The Forge SDK code examples on this page use the requestAtlassian module, which is available from the @forge/api package. This package module uses the app's credentials, determined by the scopes defined in the app's manifest.

Register a dynamic module

Send a POST request to /forge/installation/v1/dynamic/module to register a dynamic module for the current app installation.

Request

Code examples

1
2
import { requestAtlassian } from "@forge/api";
const payload = {
  key: "unique-module-key",
  type: "trigger",
  data: {
    key: "trigger-key",
    events: [
      "avi:jira:updated:issue"
    ],
    "endpoint": "some-endpoint"
  }
}
const response = await requestAtlassian(`/forge/installation/v1/dynamic/module/`, {
  headers: {
    'Content-Type': 'application/json'
  },
  method: 'POST',
  body: JSON.stringify(payload),
});
const body = await response.text(); 
console.log(`Response: ${response.status} ${body}`);

Responses

201: OK

The dynamic module was successfully registered on the installation.

4XX Error codes

1
2
{
  "message": "Authorization failed"
}

500: Internal Server Error

The Dynamic Module service encountered an unexpected problem.

1
2
{
  "message": "An internal error occurred"
}

Update a registered module

Send a PUT request to /forge/installation/v1/dynamic/module/<key> to update a dynamic module registered on the installation (identified by the module's key).

Request

Code examples

1
2
import { requestAtlassian } from "@forge/api";
const key = "unique-module-key";
const payload = {
  key: "unique-module-key",
  type: "trigger",
  data: {
    key: "trigger-key",
    events: [
      "avi:jira:updated:issue"
    ],
    "endpoint": "some-endpoint"
  }
}
const response = await requestAtlassian(`/forge/installation/v1/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}`);

Responses

200: OK

The taget dynamic module was successfully updated. The response will contain the payload of the updated dynamic module.

Example

1
2
{
  "key": "unique-module-key",
  "type": "trigger",
  "data": {
    "key": "trigger-key",
    "events": [
      "avi:jira:updated:issue"
    ],
    "endpoint": "some-endpoint"
  }
}

4XX Error codes

1
2
{
  "message": "Key cannot be modified during update"
}

500: Internal Server Error

The Dynamic Module service encountered an unexpected problem.

1
2
{
  "message": "An internal error occurred"
}

List registered modules

Send a GET request to /forge/installation/v1/dynamic/module/ to retrieve a paginated list of dynamic modules currently registered on the app installation.

Request

Code examples

1
2
import { requestAtlassian } from "@forge/api";
const params = new URLSearchParams({
  limit: '10',
  nextPageToken: '<PAGINATION-TOKEN>'
}).toString();
const response = await requestAtlassian(`/forge/installation/v1/dynamic/module/?${params}`, {
  headers: {
    'Content-Type': 'application/json'
  },
  method: 'GET'
});
const body = await response.text(); 
console.log(`Response: ${response.status} ${body}`);

Responses

200: OK

Dynamic modules were successfully fetched.

Example

1
2
{
  "key": "a-dynamic-module",
  "type": "trigger",
  "data": {
    "key": "trigger-key",
    "function": "jira-updated-issue-handler",
    "events": [
      "avi:jira:updated:issue"
    ]
  }
},
{
  "key": "another-dynamic-module",
  "type": "trigger",
  "data": {
    "filter": {
      "expression": "event.issue.fields?.issueType.name == 'Bug'",
      "onError": "RECEIVE_AND_LOG"
    },
    "key": "another-trigger-key",
    "endpoint": "some-endpoint",
    "events": [
      "avi:jira:updated:issue"
    ]
  }
}

4XX Error codes

1
2
{
  "message": "Authorization failed"
}

500: Internal Server Error

The Dynamic Module service encountered an unexpected problem.

1
2
{
  "message": "An internal error occurred"
}

Retrieve a registered module

Send a GET request to /forge/installation/v1/dynamic/module/<key> to retrieve a registered dynamic module on the installation (identified by the module's key).

Request

Code examples

1
2
import { requestAtlassian } from "@forge/api";
const key = '<YOUR-MODULE-KEY>';
const response = await requestAtlassian(`/forge/installation/v1/dynamic/module/${key}`, {
  headers: {
    'Content-Type': 'application/json'
  },
  method: 'GET'
});
const body = await response.text(); 
console.log(`Response: ${response.status} ${body}`);

Responses

200: OK

The specified dynamic module was successfully fetched.

Example

1
2
{
  "key": "a-dynamic-module",
  "type": "trigger",
  "data": {
    "key": "trigger-key",
    "events": [
      "avi:confluence:viewed:page"
    ],
    "function": "confluence-viewed-handler"
  }
}

4XX Error codes

1
2
{
  "message": "Authorization failed"
}

500: Internal Server Error

The Dynamic Module service encountered an unexpected problem.

1
2
{
  "message": "An internal error occurred"
}

Delete a registered module

Send a DELETE request to forge/installation/v1/dynamic/module/<key> to delete a registered dynamic module on the installation (identified by the module's key).

Request

Code examples

1
2
import { requestAtlassian } from "@forge/api";
const moduleKey = '<YOUR-MODULE-KEY>';
const response = await requestAtlassian(`/forge/installation/v1/dynamic/module/${moduleKey}`, {
  headers: {
    'Content-Type': 'application/json'
  },
  method: 'DELETE'
});
console.log(`Response: ${response.status}`);

Responses

204: No Content

No content will be returned if the target dynamic module was successfully deleted.

4XX Error codes

1
2
{
  "message": "Authorization failed"
}

500: Internal Server Error

The Dynamic Module service encountered an unexpected problem.

1
2
{
  "message": "An internal error occurred"
}