Modules

Within the manifest.yml file, the modules dictionary defines the functions that contain your app's logic, and the different extensions your app uses to integrate with Atlassian products.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

modules:
  macro:
    - key: hello-world-macro
      function: hello-world-macro-func
      title: Hello world macro!
      description: Inserts hello world!
  webtrigger:
    - key: webtrigger-sync
      function: my-forge-app-sync-func
    - key: my-webtrigger-async
      function: my-async-func
  trigger:
    - key: issue-creation-trigger
      events:
        - avi:activity:created:issue
        - avi:activity:updated:issue
      function: issue-trigger-func
  jira:workflowValidator:
    - key: my-forge-workflow-validator
      name: My example Forge workflow validator
      description: The description of my example Forge workflow validator
      function: my-forge-validator-function
  function:
    - key: my-forge-app-sync-func
      handler: index.runSync
    - key: my-async-func
      handler: index.runAsync
    - key: hello-world-macro-func
      handler: macro.run
    - key: issue-trigger-func
      handler: jira.issueCreationTrigger
    - key: my-forge-validator-function
      handler: index.runValidate

Function

The function module is where the app's behavior is defined. Other modules specify the function module that defines the actions to take.

Properties

Confluence content action

The confluence:contentAction module adds a menu item to the more actions (…) menu for pages and blogs. When the menu item is clicked, the module’s function renders a modal dialog. See the ContentAction component documentation for an example.

Properties

Confluence content byline item

The confluence:contentBylineItem module adds an entry to the content byline section, which is the part of the content under the title that includes metadata about contributors and more. The title of the module renders as a list item. When a user clicks the content byline item, the Forge app renders in an inline dialog.

In the app, the ContentBylineItem should be used along with InlineDialog UI components.

Properties

Confluence context menu

The confluence:contextMenu module displays an entry in the context menu when a user selects some text on a page or blog. All modules are grouped under the dropdown button in the menu. The title of the module renders as a menu item. When a user clicks the context menu item, the Forge app renders in an inline dialog.

The selected text is passed to the Forge app as a part of extensionContext, and is retrieved using the useProductContext hook. In the app, the ContextMenu should be used along with InlineDialog UI components. See the Dictionary app for an example.

Properties

Confluence global settings

The confluence:globalSettings module adds a link to the left navigation menu in Confluence global settings. Clicking the link shows the module's content. You can use the storage API with the confluence:globalSettings to store Confluence global settings in your Forge app storage. See the GlobalSettings component documentation for an example.

Properties

Confluence homepage feed

The confluence:homepageFeed module displays content in the right panel of the Confluence Home page. Each module represents a separate section in the panel, and the title of each module is used as a section title. When a user clicks an app title, the corresponding section is expanded, and the Forge app is rendered as content.

In the app, the HomepageFeed component should be used as a top-level component.

Properties

Confluence space settings

The confluence:spaceSettings module adds a tab inside the integration settings of a Confluence space. Clicking the tab shows the module's content. See the SpaceSettings component documentation for an example.

Properties

Jira custom field

The jira:customField module creates a new custom field in Jira, which makes it easier for users to add information to issues, specific to their teams' needs.

Data storage

Custom field values are stored in Jira using issue properties.

You can use the issue property key defined in the manifest to set and update the values directly using the Issue properties REST API. By doing this, you have more control over the field values, and you can update multiple issues in one request. This is especially important for read-only fields, as it's the only way of updating them.

Otherwise, custom fields (those that aren't read-only) can also be modified using the UI or with the Edit issue REST API.

Read-only fields

Read-only fields are those that have the read-only set to true in their definition in the manifest. They aren't editable by users, neither through the UI nor the Edit issue REST API. The only way to set their value is by editing their corresponding issue property.

They are great for showing values derived from the issue state. While you can show anything using issue panels or issue glances, custom fields might be a better choice if you need all their benefits, like JQL search, configuration on screens, or being part of the issue import and export.

The value of such fields has to be calculated beforehand and set on the issue property. One pattern to achieve this would be to listen to product triggers for events that might affect the values and update the values accordingly whenever necessary.

Check out this example app to see a read-only field in action: Attachment Count Custom Field.

Data types

Each field has to be based on a selected data type. The data type controls what kind of values are stored in the issue property, the field's behavior in JQL, and the default rendering behavior.

Available data types are:

• string - values are stored as plain strings. JQL offers autocomplete and exact comparison.
• number - values are stored as numbers (double-precision 64-bit IEEE 754 floating points).
• user - values are stored as strings that represent Atlassian account IDs. The field behaves like any other user field in Jira when you interact with it in the UI or the REST API.
• group - values are stored as strings that represent Atlassian group names. The field behaves like any other group field in Jira when you interact with it in the UI or the REST API.

Collection types

In addition to a single value, Forge custom fields can store collections of values. This is done by declaring the collection property, which specifies the collection type. For example, to create a field that stores a list of strings, declare it as:

1
2

type: string
collection: list

The field behaves according to its base type, but the values are stored and returned as a list.

The following types can be part of a collection:

• string
• group
• user

Note, using any other type in combination with collection:list prevents the field from appearing in Jira, even if the app is installed successfully.

Field lifecycle

A locked instance of each field defined in the manifest is created upon deployment. Whenever a field is added to the app, or an existing field is modified or removed, you need to redeploy the app to make these changes appear in Jira.

It may take some time for the custom field to be created in Jira. Try visiting or refreshing the custom fields page after a few minutes if your field is not visible.

The created field has its key set to {app-id-uuid}__{environment}__{extension-key}, where:

• {app-id-uuid} is the tail part of your app ID defined in the manifest (for example: ari:cloud:ecosystem::app/{app-id-uuid}).
• {environment} is the environment in which the app is installed.
• {extension_key} is the key of the custom field extension defined in the manifest.

This key can be used to uniquely identify the field in Jira REST APIs.

The field disappears when the app is uninstalled or if the field is removed from the manifest. If the app is reinstalled, or the field is restored, the field will reappear with all the previous data intact.

Rendering

Forge apps can optionally provide their own rendering of the field by specifying the function property.

The rendering function must return a CustomField Forge UI component. Inside the function, you can obtain the current value of the field from the useProductContext hook, like this:

1

const { platformContext: { fieldValue } } = useProductContext();

Default rendering, appropriate to the field's data type, is used if the function is not provided.

Check out this example app to see custom rendering in action: Issue Progress Custom Field.

Editing

Forge apps can optionally provide their own editing experience of the field by specifying the edit property.

The edit function must return a CustomFieldEdit Forge UI component. Inside the function, you can obtain the current value of the field from the useProductContext hook, like this:

1

const { platformContext: { fieldValue } } = useProductContext();

Default editing, appropriate to the field's data type, is used if the edit function is not provided.

Check out this example app to see custom editing in action: Risk assessment custom field.

Properties

1
2
3
4
5
6
{
   "attachments": {
     "count": 4,
     "extensions": ["txt", "pdf"]
   }
}

1
2
3
issueProperty:
    key: issueStats
    path: attachments.count

Example

The following example declares a number-type field whose values must be numbers between 0 and 100:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

jira:customField:
  - key: issue-progress
    name: Issue progress
    description: The progress of the issue, on a scale from 0 to 100.
    data:
      type: number
      storage:
        issueProperty:
          key: issueProgressForgeField
      validation:
        expression: value == null || (value >= 0 && value <= 100)
        message: The value must be a number between 0 and 100.
    readOnly: false
    function: renderIssueProgress
    edit: 
      function: editIssueProgress

Jira issue action

The jira:issueAction module adds a menu item to the more actions (…) menu on the issue view. When the menu item is clicked, the module’s function renders a modal dialog.

This module can be used in Jira Core, Jira Software, and Jira Service Desk. It works in the new issue view but not the old issue view. See the IssueAction component documentation for an example.

Properties

Jira issue activity

The jira:issueActivity module adds a item to the Activity panel of Jira issues.

This module can be used in Jira Core, Jira Software, and Jira Service Desk. It works in the new issue view but not the old issue view. See the IssueActivity component documentation for an example.

Properties

Jira issue glance

The jira:issueGlance module adds an issue glance to Jira, which is content that is shown/hidden in an issue by clicking a button. The button for the issue glance is placed alongside fields such as Assignee and Labels. Clicking the button opens the content provided by the Forge app, so that it fills the right sidebar.

This module can be used in Jira Core, Jira Software, and Jira Service Desk. It works in the new issue view but not the old issue view. See the IssueGlance component documentation for an example.

Properties

Status properties

Status value properties

Jira issue panel

The jira:issuePanel module adds an issue panel to Jira, which is content that is shown above the Activity panel on a Jira issue.

This module can be used in Jira Core, Jira Software, and Jira Service Desk. It works in the new issue view but not the old issue view. See the IssuePanel component documentation for an example.

Properties

Jira workflow validator

The jira:workflowValidator module creates a workflow validator that can be configured on workflow transitions in classic projects.

Validating with lambda functions

The function configured for the validator is invoked on every transition that the validator has been added to. When the function is invoked, it is passed an argument that contains information about the transition, that is:

1
2
3
4
5
6
7
8
9
10
11
12
13

{
  "issue": {
    "key": "issue key"
  },
  "transition": {
    "from": {
      "id": "status id"
    },
    "to": {
      "id": "status id"
    }
  }
}

The validator returns an object containing two properties:

• result - a boolean value indicating whether or not the transition is allowed.
• errorMessage - the error message to show if the result is false. Otherwise this property is ignored and doesn't have to be included.

For example:

1
2
3
4

{
  "result": false,
  "errorMessage": "An error message explaining why the validator rejected the transition"
}

Validating with Jira expressions

It’s possible to provide a Jira expression instead of a function if you’re only checking the state of the current issue.

For example, a validator that checks if the issue is assigned would look like this:

1
2
3
4
5
6

jira:workflowValidator:
  - key: my-forge-workflow-validator
    name: Issue is assigned validator
    description: This validator allows the transition where the issue has an assignee.
    expression: issue.assignee != null
    errorMessage: "The transition failed because no one is assigned to the task. Assign the task to a user and try again."

The issue validated by the expression includes changes made on the transition screen, which makes this way of defining validators particularly suitable for cases where the state to validate can be modified during the transition.

Properties

Macro

The macro module inserts dynamic content into the user interface via an editor. Currently, the macro module works in Confluence, where the macro is added to a page via the quick insert menu of the editor. The macro module is implemented by a Forge function. See the Macro component documentation for an example.

Properties

Scheduled trigger

The scheduledTrigger module repeatedly invokes a function on a scheduled interval. Each trigger is scheduled to start shortly after it is created, which is at 10 minutes after app installation, and at one minute after app deployment. It then runs hourly after that.

On each app deployment or app installation, all existing scheduled triggers are removed. After that, any scheduled triggers declared in the manifest are recreated.

Scheduled triggers run without a user context, which means the principal field of the context argument doesn't represent a user. If a function invoked from a scheduled trigger returns a value, it is ignored. If the function throws an error, nothing will happen, and the function invocation will not be retried. The function will be invoked the next time the schedule is due.

Apps can declare up to three scheduled triggers in their manifest.

See Extending your app with a scheduled trigger for step-by-step instructions on how to use this module type.

Properties

Trigger

The trigger module invokes a function when a product event is fired. For example, as the result of an issue being created in Jira.

Web trigger

The webtrigger module invokes a function as the result of an HTTP request. To obtain a URL to call a web trigger, define a webtrigger module then run forge webtrigger in the Forge CLI.

Properties

Example web trigger URL

1

https://406d303d-0393-4ec4-ad7c-1435be94583a.hello.atlassian-dev.net/x0/eyJjdHgiOiJhcmk6Y2xvdWQ6Y29uZmx1ZW5jZTo6c2l0ZS9EVU1NWS0xNThjODIwNC1mZjNiLTQ3YzItYWRiYi1hMDkwNmNjYzcyMmIiLCJleHQiOiJhcmk6Y2xvdWQ6ZWNvc3lzdGVtOjpleHRlbnNpb24vNDA2ZDMwM2QtMDM5My00ZWM0LWFkN2MtMTQzNWJlOTQ1ODNhL2ZjMTI1ZTY3LTY0MTItNGVjNi04OTRhLWU5OTVjZjcyZDcyYS9zdGF0aWMvd2VidHJpZ2dlci1zeW5jIn0