Rate this page:
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.
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:jira:created:issue
- avi:jira: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
The function
module is where the app's behavior is defined. Other modules specify the function module
that defines the actions to take.
Property | Type | Required | Description |
---|---|---|---|
key |
| Yes | A key for the module, which other modules can refer to. Must be unique within the manifest and have a maximum of 23 characters. Regex: |
handler |
| Yes | A pointer to the function responsible for handling invocations. Expected format: For example, Regex: |
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.
Property | Type | Required | Description |
---|---|---|---|
key |
| Yes | A key for the module, which other modules can refer to. Must be unique within the manifest. Regex: |
function | string | The content action module requires either a function for usage with the UI kit, or a resource when building with custom UI. | A reference to the function module that defines the content action. This function must return the ContentAction component, which renders the modal dialog for its content. |
resource | string | A reference to the static resources entry that your content action wants to display. See resources for more details. | |
resolver | { function: string } | Contains a function property, which references the function module that defines the configuration of resource . Can only be set if the module is using the resource property. | |
viewportSize | 'small' , 'medium' , 'large' or 'xlarge' | The display size of resource . Can only be set if the module is using the resource property. | |
title | string | Yes | The title of the content action, which is displayed as a menu item. |
description | string | The description of the content action. |
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
, icon
, and tooltip
of the module render togther as a list item.
In the app, the ContentBylineItem should be used along with InlineDialog UI kit components.
Property | Type | Required | Description |
---|---|---|---|
key |
| Yes | A key for the module, which other modules can refer to. Must be unique within the manifest. Regex: |
function | string | The content byline item module requires either a function for usage with the UI kit, or a resource when building with custom UI. | A reference to the function module that defines the content byline item. |
resource | string | A reference to the static resources entry that your content byline item wants to display. See resources for more details. | |
resolver | { function: string } | Contains a function property, which references the function module that defines the configuration of resource . Can only be set if the module is using the resource property. | |
viewportSize | 'small' , 'medium' or 'large' | The display size of resource . Can only be set if the module is using the resource property. | |
title | string | Yes | The title of the content byline item, which is displayed as a list item. |
icon | string | The URL of the icon that's displayed as an icon next to the link title. A generic app icon is displayed if no icon is provided, or if there’s an issue preventing the icon from loading. | |
tooltip | string | The tooltip of the content byline item, which is displayed on hover. | |
description | string | The description of the content byline item. | |
dynamicProperties | { function: string } | Contains a function property, which references the function module that defines the configuration of resource . See Dynamic properties for more details.
|
Dynamic properties are used to dynamically update the title
, icon
, or tooltip
properties of the
confluence:contentBylineItem
module. If provided in the manifest.yml
file, Confluence attempts
to retrieve the dynamic properties on the initial render of the app. To do this, the dynamicProperties
handler function of the app is called. When the content byline item is clicked, the app renders in a
dialog, where it can perform business logic updates. After the dialog is closed, the handler function
is again called to retrieve updates, and then update the title
, icon
, or tooltip
.
The app's handler function is passed two arguments: payload
and context
. The payload
object has the following structure:
Property | Type | Description |
---|---|---|
cloudId | string | The cloudId for your site. |
localId | string | A unique id for this instance of this component in the content. |
module | object | Contextual information about the current environment that depends on the module being used. The type of this variable depends on the data type of the field. |
module:type | string | The module type included in the manifest.yml file. In this case, it is the confluence:contentBylineItem module. |
module:content | object | Details about the type of content. |
module: content: id | string | The unique identifier of the Confluence content. |
module: content: type | string | The type of Confluence content on which the invocation has occurred. Valid values are page , blogpost , and space . |
module:space | object | Details about the space from which the invocation originates. |
module: space: key | string | The key of the originating space. |
The context
object has the following structure:
1 2 3 4 5 6
interface Context {
principal: {
accountId: string;
};
installContext: string;
}
The handler function should return (or resolve with) a plain old JavaScript object with a title
,
icon
, and tooltip
as keys. These optional keys are only sent if their
respective values require updating. Failure to provide a key would default to the last used value
or the original values defined within the manifest.yml
file.
Below is an example of a handler function returning a returned object:
1 2 3 4 5 6 7
function handlerFunction(contextPayload) {
return {
"title": "Updated title"
"icon": "https://mydomain.com/my-icon.png",
"tooltip": "Updated Tooltip"
};
}
Check out the Page approver app as an example of
an app that updates the title and tooltip on change, and prepopulates a default icon that's missing
from the manifest.yml
file.
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 kit components. See the Dictionary app for an example.
Property | Type | Required | Description |
---|---|---|---|
key |
| Yes | A key for the module, which other modules can refer to. Must be unique within the manifest. Regex: |
function | string | The context menu module requires either a function for usage with the UI kit, or a resource when building with custom UI. | A reference to the function module that defines the context menu app. |
resource | string | A reference to the static resources entry that your context menu app wants to display. See resources for more details. | |
resolver | { function: string } | Contains a function property, which references the function module that defines the configuration of resource . Can only be set if the module is using the resource property. | |
viewportSize | 'small' , 'medium' or 'large' | The display size of resource . Can only be set if the module is using the resource property. | |
title | string | Yes | The title of the context menu app, displayed as a menu item. |
description | string | The description of the context menu app. |
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.
Property | Type | Required | Description |
---|---|---|---|
key |
| Yes | A key for the module, which other modules can refer to. Must be unique within the manifest. Regex: |
function | string | The global settings module requires either a function for usage with the UI kit, or a resource when building with custom UI. | A reference to the function module that defines the Confluence global settings app. |
resource | string | A reference to the static resources entry that your Confluence global settings app wants to display. See resources for more details. | |
resolver | { function: string } | Contains a function property, which references the function module that defines the configuration of resource . Can only be set if the module is using the resource property. | |
title | string | Yes | The title of the global settings, which is displayed as the title of the link and header of the page. |
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.
Property | Type | Required | Description |
---|---|---|---|
key |
| Yes | A key for the module, which other modules can refer to. Must be unique within the manifest. Regex: |
function | string | The homepage feed module requires either a function for usage with the UI kit, or a resource when building with custom UI. | A reference to the function module that defines the Confluence homepage feed app. |
resource | string | A reference to the static resources entry that your Confluence homepage feed app wants to display. See resources for more details. | |
resolver | { function: string } | Contains a function property, which references the function module that defines the configuration of resource . Can only be set if the module is using the resource property. | |
viewportSize | 'small' , 'medium' , 'large' or 'xlarge' | The display size of resource . Can only be set if the module is using the resource property. | |
title | string | Yes | The title of the homepage feed app, displayed as a section title. |
description | string | The description of the homepage feed app. |
The confluence:spacePage
module displays content in place of a Confluence page.
Each module appears as a link in the space navigation menu, and the title of each module is used
as the title of the link. When a user clicks a link, the corresponding Forge app renders inside the content area of Confluence.
The URL is updated with the following app information in the form of: /spaces/:spaceKey/apps/:appId/:forgeEnvId/:route
. You can configure :route
in the manifest.
In the app, the SpacePage component should be used as a top-level component.
Property | Type | Required | Description |
---|---|---|---|
key |
| Yes | A key for the module, which other modules can refer to. Must be unique within the manifest. Regex: |
function | string | The space page module requires either a function for usage with the UI kit, or a resource when building with custom UI. | A reference to the function module that defines the Confluence space page app. |
resource | string | A reference to the static resources entry that your Confluence space page app wants to display. See resources for more details. | |
resolver | { function: string } | Contains a function property, which references the function module that defines the configuration of resource . Can only be set if the module is using the resource property. | |
title | string | Yes | The title of the space page app, displayed as a link title. |
icon | string | The URL of the icon that's displayed as an icon next to the link title. A generic app icon is displayed if no icon is provided. | |
route | string | Yes | A string of text that makes the URL of the browser more readable. Inside an app, each space page module must have a distinct Regex: |
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.
Property | Type | Required | Description |
---|---|---|---|
key |
| Yes | A key for the module, which other modules can refer to. Must be unique within the manifest. Regex: |
function | string | The space settings module requires either a function for usage with the UI kit, or a resource when building with custom UI. | A reference to the function module that defines the Confluence space settings app. |
resource | string | A reference to the static resources entry that your Confluence space settings app wants to display. See resources for more details. | |
resolver | { function: string } | Contains a function property, which references the function module that defines the configuration of resource . Can only be set if the module is using the resource property. | |
title | string | Yes | The title of the space settings, which is displayed as the title of the tab. |
The jira:adminPage
module adds an item in the Apps
section of the left navigation of Jira admin
settings. When the item is clicked, content is rendered on a new Jira page.
You can use the UI kit or custom UI
to create content for the Jira page. When using the UI kit in the app, use the
AdminPage component as a top-level component.
The page URL is constructed in the form of: /jira/settings/apps/{appId}/{envId}
This module can be used in Jira Core, Jira Software, and Jira Service Management.
Property | Type | Required | Description |
---|---|---|---|
key |
| Yes |
A key for the module, which other modules can refer to. Must be unique within the manifest. Regex: |
function | string | The admin page module requires a function for use with the UI kit or a resource when building with custom UI. | A reference to the function module that defines the admin page. This function must return the AdminPage component. |
resource | string | A reference to the static resources entry that your admin page wants to display. See resources for more details. | |
resolver | { function: string } | Contains a function property, which references the function module that defines the configuration of resource . Can only be set if the module is using the resource property. | |
title | string | Yes | The title of the admin page, which is displayed at the top of the page. The title also appears as an item in the `Apps` section of the left navigation of Jira admin settings. |
icon | string | The URL of the icon that's displayed next to the title. A generic app icon is displayed if no icon is provided. | |
layout | native|basic (default: native ) | The layout of the admin page, which defines the elements that should be displayed on the page (for example, page title). |
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.
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 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.
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.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:
Note, using any other type in combination with collection:list
prevents the field from appearing
in Jira, even if the app is installed successfully.
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 must redeploy the app to make these changes appear in Jira.
To make a custom field appear in Jira, you must add the custom field to a screen first. 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.
Forge apps can optionally provide their own rendering of the field by specifying the function
property.
The rendering function must return a CustomField UI kit component. Inside the function, you can obtain the current value of the field from the useProductContext hook, like this:
1
const { extensionContext: { 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.
Forge apps can optionally provide their own editing experience of the field by specifying the edit
property.
The edit function must return a CustomFieldEdit UI kit component. Inside the function, you can obtain the current value of the field from the useProductContext hook, like this:
1
const { extensionContext: { 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.
Property | Type | Required | Description |
---|---|---|---|
key |
| Yes |
A key for the module, which other modules can refer to. Must be unique within the manifest.
This key becomes a part of the custom field key as described in the Field lifecycle section. Regex: |
name | string | Yes | The name of the field. |
description | string | Yes | The description of the field. |
type | string | Yes | The type of the value stored by the field. Available types are:
|
collection | none|list (default: none ) | The kind of collection that the field values should be stored in. See collection types for more details. | |
issueProperty:key | string | Yes | The key of the issue property that stores the value of the field. Make sure this key is unique to avoid potential clashes with properties from other apps. For example, you can use the name of your app or your company as a prefix for this key. |
issueProperty:path | string | No Only allowed if readOnly is true . | The path within the JSON object that’s stored in the issue property.
The value extracted from the JSON object using the given path will be used as the value of the field.
For example, you may store the following JSON object in an issue property under key issueStats: For a read-only field that displays the attachment count (4 in this case), part of the declaration related to where the value is stored would look like this: This only applies to read-only fields. Editable fields must store the field value in the property directly. |
validation:expression | string | A Jira expression
that validates the field's value before it's set. The expression must return a boolean value.
Note that the value is validated only when edited through the UI or issue APIs.
Setting the issue property directly won't trigger the validation.
The expression is evaluated with the following context variables: | |
validation:errorMessage | string | The error message to show when the validation fails. | |
readOnly | boolean | Whether or not the field is read-only. Read-only fields can't be edited by users. Defaults to false . | |
function | string | A reference to the function module that provides the field rendering. This function must return the CustomField component. | |
edit:function | string | A reference to the function module that provides the field editing experience. | |
displayConditions | object | The object that defines whether or not a module is displayed in the UI of the app. See display conditions. |
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
jira:customField:
- key: issue-progress
name: Issue progress
description: The progress of the issue, on a scale from 0 to 100.
type: number
issueProperty:
key: issueProgressForgeField
validation:
expression: value == null || (value >= 0 && value <= 100)
errorMessage: The value must be a number between 0 and 100.
readOnly: false
function: renderIssueProgress
edit:
function: editIssueProgress
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.
Property | Type | Required | Description |
---|---|---|---|
key |
| Yes | A key for the module, which other modules can refer to. Must be unique within the manifest.
Regex: |
function | string | The issue action module requires either a function for usage with the UI kit, or a resource when building with custom UI. | A reference to the function module that defines the issue action. This function must return the IssueAction component, which renders the modal dialog for its content. |
resource | string | A reference to the static resources entry that your issue action wants to display. See resources for more details. | |
resolver | { function: string } | Contains a function property, which references the function module that defines the configuration of resource . Can only be set if the module is using the resource property. | |
viewportSize | 'small' , 'medium' , 'large' or 'xlarge' | The display size of resource . Can only be set if the module is using the resource property. | |
title | string | Yes | The title of the issue action, which is displayed as a menu item. |
displayConditions | object | The object that defines whether or not a module is displayed in the UI of the app. See display conditions. |
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.
Property | Type | Required | Description |
---|---|---|---|
key |
Pattern: | Yes | A key for the module, which other modules can refer to. Must be unique within the manifest. |
function | string | The issue activity module requires either a function for usage with the UI kit, or a resource when building with custom UI. | A reference to the function module that defines the issue activity. This function must return the IssueActivity component. |
resource | string | A reference to the static resources entry that your issue activity wants to display. See resources for more details. | |
resolver | { function: string } | Contains a function property, which references the function module that defines the configuration of resource . Can only be set if the module is using the resource property. | |
viewportSize | 'small' , 'medium' , 'large' or 'xlarge' | The display size of resource . Can only be set if the module is using the resource property. | |
title | string | Yes | The title of the issue activity, which is displayed as a tab item. |
displayConditions | object | The object that defines whether or not a module is displayed in the UI of the app. See display conditions. |
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.
Property | Type | Required | Description |
---|---|---|---|
key |
| Yes |
A key for the module, which other modules can refer to. Must be unique within the manifest. Regex: |
function | string | The issue glance module requires either a function for usage with the UI kit, or a resource when building with custom UI. | A reference to the function module that defines the issue glance. This function must return the IssueGlance component. |
resource | string | A reference to the static resources entry that your issue glance wants to display. See resources for more details. | |
resolver | { function: string } | Contains a function property, which references the function module that defines the configuration of resource . Can only be set if the module is using the resource property. | |
title | string | Yes | The title of the issue glance, which is displayed above its label. |
label | string | Yes | The text shown on the button for the issue glance. |
status | object | The badge or lozenge shown next to the label . If status is not
specified, then no badge or lozenge is shown. See status properties. | |
displayConditions | object | The object that defines whether or not a module is displayed in the UI of the app. See display conditions. |
Property | Type | Required | Description |
---|---|---|---|
type | 'badge' | 'lozenge' | Yes | The UI element used to display the status. |
value | object | Yes |
This property is an object representing the status value. See status value properties. |
Property | Type | Required | Description |
---|---|---|---|
label | string | Yes | The text to display in the status. If |
type | 'default' | 'inprogress' | 'moved' | 'new' | 'removed' | 'success' |
If |
The jira:issuePanel
module adds an issue panel to a Jira issue when a configured button is clicked.
The content of the module 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 more details.
Property | Type | Required | Description |
---|---|---|---|
key |
| Yes |
A key for the module, which other modules can refer to. Must be unique within the manifest. Regex: |
function | string | The issue panel module requires either a function for usage with the UI kit, or a resource when building with custom UI. | A reference to the function module that defines the issue panel. This function must return the IssuePanel component. |
resource | string | A reference to the static resources entry that your issue panel wants to display. See resources for more details. | |
resolver | { function: string } | Contains a function property, which references the function module that defines the configuration of resource . Can only be set if the module is using the resource property. | |
viewportSize | 'small' , 'medium' , 'large' or 'xlarge' | The display size of resource . Can only be set if the module is using the resource property. | |
title | string | Yes | The title of the issue panel, which is displayed above the panel. The title also appears in the ••• menu that’s clicked to display the issue panel. |
icon | string | Yes | The URL of the icon that will be displayed as a button. When the button is clicked, an issue panel is added to the issue view. |
allowMultiple |
|
Controls whether or not multiple instances of the issue panel are shown when clicking the issue panel button repeatedly. Defaults to If set to | |
displayConditions | object | The object that defines whether or not a module is displayed in the UI of the app. See display conditions. |
The jira:projectPage
module adds an item in the Apps
section of the left navigation of Jira
company-managed project settings. When the item is clicked, content is rendered on a new Jira page.
You can use the UI kit or custom UI
to create content for the Jira page. When using the UI kit in the app, use the
ProjectPage component as a top-level component.
The page URL is constructed in the form of: /jira/{projectType}/projects/{projectKey}/apps/{appId}/{envId}
This module can be used in Jira Core, Jira Software, and Jira Service Management.
Property | Type | Required | Description |
---|---|---|---|
key |
| Yes |
A key for the module, which other modules can refer to. Must be unique within the manifest. Regex: |
function | string | The project page module requires a function for use with the UI kit or a resource when building with custom UI. | A reference to the function module that defines the project page. This function must return the ProjectPage component. |
resource | string | A reference to the static resources entry that your project page wants to display. See resources for more details. | |
resolver | { function: string } | Contains a function property, which references the function module that defines the configuration of resource . Can only be set if the module is using the resource property. | |
title | string | Yes | The title of the project page, which is displayed at the top of the page. The title also appears as an item in the `Apps` section of the left navigation of Jira company-managed project settings. |
icon | string | The URL of the icon that's displayed next to the title. A generic app icon is displayed if no icon is provided. | |
layout | native|basic (default: native ) | The layout of the admin page, which defines the elements that should be displayed on the page (for example, page title). |
The jira:workflowValidator
module creates a workflow validator that can be configured on workflow
transitions in company-managed 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"
}
}
}
The function 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, to create a validator that allows transitions only for issues in the project with key PRO
, declare it like this in the manifest:
1 2 3 4 5 6 7 8
jira:workflowValidator:
- key: my-forge-workflow-validator
name: Project is PRO validator
description: This validator will allow the transition only if the project is PRO.
function: validate
function:
- key: validate
handler: status.validate
To implement the actual logic in the src/status.js
file:
1 2 3 4 5 6 7 8
export const validate = (args) => {
const issueKey = args.issue.key;
return {
result: issueKey.startsWith('PRO'),
errorMessage: 'Only PRO project can use this flow'
};
}
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.
Property | Type | Required | Description |
---|---|---|---|
key |
| Yes |
A key for the module, which other modules can refer to. Must be unique within the manifest. Regex: |
name | string | Yes | The name of the validator displayed in the workflow configuration. |
description | string | Yes | The description of the validator, shown when adding the validator to a transition. |
function | string | The 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. |
expression | string | The expression used to validate whether or not the transition should be allowed.
The expression is evaluated with the following context variables: | |
errorMessage | string | The error message to show when the validation fails. If `errorMessage` is not provided, the default error message will be displayed. |
The macro
module inserts dynamic content into the user interface via an editor. Editor macros are
only compatible with the Atlassian editor. All cloud sites use the Atlassian editor by default.
The macro
module works in Confluence, where the macro is inserted by typing "/" and selecting
from the quick insert menu of the editor. The macro
module is implemented by a Forge function.
See the Macro component documentation for an example.
Property | Type | Required | Description |
---|---|---|---|
key |
| Yes |
A key for the module, which other modules can refer to. Must be unique within the manifest. Regex: |
function | string | The macro module requires either a function for usage with the UI kit, or a resource when building with custom UI. | A reference to the function module that defines the macro. |
resource | string | A reference to the static resources entry that your macro wants to display. See resources for more details. | |
resolver | { function: string } | Contains a function property, which references the function module that defines the configuration of resource . Can only be set if the module is using the resource property. | |
viewportSize | 'small' , 'medium' , 'large' or 'xlarge' | The display size of resource . Can only be set if the module is using the resource property. | |
title | string | Yes | The title of the macro. In Confluence, this is displayed in the editor. |
description | string | The description of the macro. In Confluence, this is displayed in the editor. | |
config | { function: string } | Contains a function property, which references the function module that defines the macro configuration. |
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 the manifest.yml
file. Apps with
scheduled triggers are limited to 100 installations, per environment.
See Extending your app with a scheduled trigger for step-by-step instructions on how to use this module type.
Property | Type | Required | Description |
---|---|---|---|
key |
| Yes |
A key for the module, which other modules can refer to. Must be unique within the manifest. Regex: |
function | string | Yes | A reference to the function module that defines the behavior. |
interval | 'hour' | Yes | The interval at which to invoke the function. |
The trigger
module invokes a function when a product event is fired. For example, as the result of
an issue being created in Jira.
Property | Type | Required | Description |
---|---|---|---|
key |
| Yes |
A key for the module, which other modules can refer to. Must be unique within the manifest. Regex: |
function | string | Yes | A reference to the function module that defines the behavior. |
events | Array<string> | Yes | A list of product events that trigger the function. |
The webtrigger
module invokes a function as the result of an HTTP request.
To obtain a URL to call a web trigger, first define a webtrigger
module,
and then run forge webtrigger
in the Forge CLI.
Note that while in beta, web triggers only work for the developer of the app.
Property | Type | Required | Description |
---|---|---|---|
key |
| Yes |
A key for the module, which other modules can refer to. Must be unique within the manifest. Regex: |
function | string | Yes | A reference to the function module that defines the behavior. |
1
https://406d303d-0393-4ec4-ad7c-1435be94583a.hello.atlassian-dev.net/x0/eyJjdHgiOiJhcmk6Y2xvdWQ6Y29uZmx1ZW5jZTo6c2l0ZS9EVU1NWS0xNThjODIwNC1mZjNiLTQ3YzItYWRiYi1hMDkwNmNjYzcyMmIiLCJleHQiOiJhcmk6Y2xvdWQ6ZWNvc3lzdGVtOjpleHRlbnNpb24vNDA2ZDMwM2QtMDM5My00ZWM0LWFkN2MtMTQzNWJlOTQ1ODNhL2ZjMTI1ZTY3LTY0MTItNGVjNi04OTRhLWU5OTVjZjcyZDcyYS9zdGF0aWMvd2VidHJpZ2dlci1zeW5jIn0
Rate this page: