Rate this page:

Manifest

About

The manifest files describes a Forge app. It’s created as part of the Forge CLI’s forge create with filename manifest.yml. The manifest uses YAML syntax.

Properties

The manifest contains two top-level properties, app and modules.

PropertyRequiredDescription
appYesInformation to identify the app, including name and Atlassian Resource Identifier (ari). These are populated as part of the forge create command.
modulesYesA list of all the modules used by the app.

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
34
35
36
app:
  id: "ari:cloud:ecosystem::app/406d303d-0393-4ec4-ad7c-1435be94583a"
  name: my-cool-forge-app
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 behaviour is defined. Other modules specify the function module that defines the actions to take.

Properties

PropertyTypeRequiredDescription
key

string

Pattern: ^[a-zA-Z0-9_\\-\\.]+$

YesA key for the module, which other modules can refer to. Must be unique within the manifest and have a maximum of 23 characters.
handler

string

Pattern: ^[a-zA-Z0-9_\\-\\.]+$

Yes

A pointer to the function responsible for handling invocations.

Expected format: file.function

For example, jira.issueCreationTrigger calls the issueCreationTrigger function defined in jira.js in the app's src directory.

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

PropertyTypeRequiredDescription
key

string

Pattern: ^[a-zA-Z0-9_\\-\\.]+$\

YesA key for the module, which other modules can refer to. Must be unique within the manifest.
functionstringYesA reference to the function module that defines the content action. This function renders the modal dialog for the component.
titlestringYesThe title of the content action, which is displayed as a menu item.
descriptionstringNoThe description of the content action.

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

PropertyTypeRequiredDescription
key

string

Pattern: ^[a-zA-Z0-9_\\-\\.]+$\

YesA key for the module, which other modules can refer to. Must be unique within the manifest.
functionstringYesA reference to the function module that defines the context menu app.
titlestringYesThe title of the context menu app, displayed as a menu item.
descriptionstringNoThe description of the context menu app.

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

PropertyTypeRequiredDescription
key

string

Pattern: ^[a-zA-Z0-9_\\-\\.]+$\

YesA key for the module, which other modules can refer to. Must be unique within the manifest.
functionstringYesA reference to the function module that defines the issue action. This function renders the modal dialog for the component.
titlestringYesThe title of the issue action, which is displayed as a menu item.

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

PropertyTypeRequiredDescription
key

string

Pattern: ^[a-zA-Z0-9_\\-\\.]+$

YesA key for the module, which other modules can refer to. Must be unique within the manifest.
functionstringYesA reference to the function module that defines the issue glance.
titlestringYesThe title of the issue glance, which is displayed above its label.
labelstringYesThe text shown on the button for the issue glance.
statusobjectNoThe badge or lozenge shown next to the label. If status is not specified, then no badge or lozenge is shown. See status properties.

Status properties

PropertyTypeRequiredDescription
type'badge' | 'lozenge'YesThe UI element used to display the status.
valueobjectYes

This property is an object representing the status value. See status value properties.

Status value properties

PropertyTypeRequiredDescription
labelstringYesThe text to display in the status.

If type is 'badge', this property is a number specified as a string (for example, '3').

Note, this value is static and can only be changed by updating the manifest.
type'default' | 'inprogress' | 'moved' | 'new' | 'removed' | 'success'No

If type is 'lozenge', this value controls the appearance of the status.

Note, this value is static and can only be changed by updating the manifest.

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

PropertyTypeRequiredDescription
key

string

Pattern: ^[a-zA-Z0-9_\\-\\.]+$

YesA key for the module, which other modules can refer to. Must be unique within the manifest.
functionstringYesA reference to the function module that defines the issue panel.
titlestringYesThe title of the issue panel, which is displayed above the panel.

Jira workflow validator

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

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"
    }
  }
}

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 if 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 validator returns an object containing two properties:

  • result - a boolean value indicating whether 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"
}

Properties

PropertyTypeRequiredDescription
key

string

Pattern: ^[a-zA-Z0-9_\\-\\.]+$

YesA key for the module, which other modules can refer to. Must be unique within the manifest.
namestringYesThe name of the validator displayed in the workflow configuration.
descriptionstringYesThe description of the validator, shown when adding the validator to a transition.
functionstringThe validator requires either the function or the expression in your Forge app. Only one of the two properties must be present in your Forge app.A reference to the function module that evaluates the validator.
expressionstringThe expression in the property receives the current state of the issue being transitioned, which is then used to validate whether or not the transition should be allowed.

The expression is evaluated with the following context variables:

  • user (User): The current user.
  • issue (Issue): The transitioned issue. Includes changes made on the transition screen.
  • project (Project): The project to which the issue belongs.

errorMessagestringNoThe error message to show when the validation fails. If `errorMessage` is not provided, the default error message will be displayed.

Macro

The macro module inserts dynamic content into the user interface via an editor. Currently, the macro module works in the 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

PropertyTypeRequiredDescription
key

string

Pattern: ^[a-zA-Z0-9_\\-\\.]+$

YesA key for the module, which other modules can refer to. Must be unique within the manifest.
functionstringYesA reference to the function module that defines the macro.
titlestringYesThe title of the macro. In Confluence, this is displayed in the editor.
descriptionstringNoThe description of the macro. In Confluence, this is displayed in the editor.

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.

PropertyTypeRequiredDescription
key

string

Pattern: ^[a-zA-Z0-9_\\-\\.]+$

YesA key for the module, which other modules can refer to. Must be unique within the manifest.
functionstringYesA reference to the function module that defines the behavior.
eventsArray<string>YesA list of product events that trigger the function.

Web trigger

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

Properties

PropertyTypeRequiredDescription
key

string

Pattern: ^[a-zA-Z0-9_\\-\\.]+$

YesA key for the module, which other modules can refer to. Must be unique within the manifest.
functionstringYesA reference to the function module that defines the behavior.

Example web trigger URL

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

Rate this page: