Display conditions

Rate this page:

Modules

While the Forge platform is generally available, some modules remain in beta. While in beta, we may make changes that might break your apps. Learn more about the Forge deprecation policy, and what this means for functionality in beta.

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: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

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

PropertyTypeRequiredDescription
key

string

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: ^[a-zA-Z0-9_-]+$

handler

string

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.

Regex: ^[a-zA-Z0-9_-]+$

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

Yes

A key for the module, which other modules can refer to. Must be unique within the manifest.

Regex: ^[a-zA-Z0-9_-]+$

functionstringThe 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.
resourcestringA 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.
titlestringYesThe title of the content action, which is displayed as a menu item.
descriptionstringThe description of the content action.

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, icon, and tooltip of the module render together as a list item.

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

Properties

PropertyTypeRequiredDescription
key

string

Yes

A key for the module, which other modules can refer to. Must be unique within the manifest.

Regex: ^[a-zA-Z0-9_-]+$

functionstringThe 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.
resourcestringA 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.
titlestringYesThe title of the content byline item, which is displayed as a list item.
iconstring

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.

tooltipstringThe tooltip of the content byline item, which is displayed on hover.
descriptionstringThe 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

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.

We're working on integrating 3LO consent with dynamic properties. If you’re using api.asUser().requestConfluence, and if your user doesn't provide consent for your app through another method, api.asUser().requestConfluence will fail to execute. The app will then use the properties configured in the manifest.yml file by default.

The app's handler function is passed two arguments: payload and context. The payload object has the following structure:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
interface Payload {
  // The cloudId for your site 
  cloudId: string;
  // A unique id for this instance of this component in the content
  localId: string;
  extension: {
    // The module type included in the manifest.yml file.
    // In this case, it is the "confluence:contentBylineItem" module.
    type: string;
    content: {
      // The unique identifier of the Confluence content
      id: string;
      // The type of Confluence content on which the invocation has occurred
      type: 'page' | 'blogpost' | 'space';
    };
    space: {
      // The key of the originating invocation space
      key: string;
    }
  };
}

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.

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 kit components. See the Dictionary app for an example.

Properties

PropertyTypeRequiredDescription
key

string

Yes

A key for the module, which other modules can refer to. Must be unique within the manifest.

Regex: ^[a-zA-Z0-9_-]+$

functionstringThe 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.
resourcestringA 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.
titlestringYesThe title of the context menu app, displayed as a menu item.
descriptionstringThe description of the context menu app.

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

PropertyTypeRequiredDescription
key

string

Yes

A key for the module, which other modules can refer to. Must be unique within the manifest.

Regex: ^[a-zA-Z0-9_-]+$

functionstringThe 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.
resourcestringA 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.
titlestringYesThe title of the global settings, which is displayed as the title of the link and header of the page.

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

PropertyTypeRequiredDescription
key

string

Yes

A key for the module, which other modules can refer to. Must be unique within the manifest.

Regex: ^[a-zA-Z0-9_-]+$

functionstringThe 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.
resourcestringA 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.
titlestringYesThe title of the homepage feed app, displayed as a section title.
descriptionstringThe description of the homepage feed app.

Confluence space page

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.

Properties

PropertyTypeRequiredDescription
key

string

Yes

A key for the module, which other modules can refer to. Must be unique within the manifest.

Regex: ^[a-zA-Z0-9_-]+$

functionstringThe 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.
resourcestringA 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.
titlestringYesThe title of the space page app, displayed as a link title.
iconstring

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.

routestringYes

A string of text that makes the URL of the browser more readable. Inside an app, each space page module must have a distinct route.

Regex: ^[0-9a-z-]+$

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

PropertyTypeRequiredDescription
key

string

Yes

A key for the module, which other modules can refer to. Must be unique within the manifest.

Regex: ^[a-zA-Z0-9_-]+$

functionstringThe 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.
resourcestringA 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.
titlestringYesThe title of the space settings, which is displayed as the title of the tab.

Jira admin page

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.

Properties

PropertyTypeRequiredDescription
key

string

Yes

A key for the module, which other modules can refer to. Must be unique within the manifest.

Regex: ^[a-zA-Z0-9_-]+$

functionstringThe 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.
resourcestringA 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.
titlestringYesThe 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.
iconstringThe URL of the icon that's displayed next to the title. A generic app icon is displayed if no icon is provided.
layoutnative|basic (default: native)The layout of the admin page, which defines the elements that should be displayed on the page (for example, page title).
displayConditionsobjectThe object that defines whether or not a module is displayed in the UI of the app. See display conditions.

Jira custom field (beta)

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.

This module can only be used in Jira company-managed projects.

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.

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 with the dedicated REST API. 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 predefined data type. The data type controls what kind of values the REST API accepts and returns for the field, the field's behavior in JQL, and the default rendering behavior.

Available data types are:

  • string - values represent plain strings. JQL offers autocomplete and exact comparison.
  • number - values represent numbers (double-precision 64-bit IEEE 754 floating points).
  • user - values represent users identified by 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 represent groups identified by names. The field behaves like any other group field in Jira when you interact with it in the UI or the REST API.
  • object - values are arbitrary JSON objects. See below for more details.
Object type

The object type makes use of some additional properties in comparison to other types.

The required formatter property contains a Jira expression that returns a string used to represent the value in places where the rendering function is not supported. For example, the column view in the Global Issue Navigator.

The optional schema property contains the JSON schema that is used to validate values stored in the field.

Here is an example of a field that stores money. It showcases the usage of both the formatter and schema properties:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
  jira:customField:
    - key: cf-type-money
      name: Development cost
      description: Tracks the development cost of features, in different currencies
      type: object
      formatter: 
        expression: "`${value.amount} ${value.currency}"
      schema:
        properties:
          amount:
            type: number
          currency:
            type: string
            enum: [ "USD", "EURO", "AUD" ]
        required: [ "amount", "currency" ]

The schema ensures that values of this field look like this:

1
2
3
4
{
  "amount": 100
  "currency": "USD"
}

With the formatter in place, displayed on the issue search, the value will be a string 100 USD.

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 following data 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 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 uppercase environment in which the app is installed.
  • {extension_key} is the key of the custom field extension defined in the manifest.

For example: 2bcdc120-765b-40a1-842b-887bdfd852ea__DEVELOPMENT__field-key.

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 UI kit component. Inside the function, you can obtain the current value, id, and full type of the field from the useProductContext hook, like this:

1
const { extensionContext: { fieldValue, fieldId, fieldType } = 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 UI kit component. Inside the function, you can obtain the current value, id, and full type of the field from the useProductContext hook, like this:

1
const { extensionContext: { fieldValue, fieldId, fieldType } = 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

PropertyTypeRequiredDescription
key

string

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: ^[a-zA-Z0-9_-]+$

namestringYesThe name of the field.
descriptionstringYesThe description of the field.
typestringYesThe type of the value stored by the field. Available types are:
  • string
  • number
  • user
  • group
collectionnone|list (default: none) The kind of collection that the field values should be stored in. See collection types for more details.
validation:
  expression
stringA Jira expression that validates the field's value before it's set by the user.

Does not apply when the app updates the value directly with the dedicated REST API.

The expression must return a boolean value.

The expression is evaluated with the following context variables:

  • user (User): The current user.
  • issue (Issue): The edited issue.
  • project (Project): The project to which the issue belongs.
  • value: The value that’s being set on the field. The type of this variable depends on the data type of the field and can be one of the following:
    • String, if the data type is string or group.
    • Number, if the data type is number.
    • User, if the data type is user.
    • Map, if the data type is object.
    If the field stores a collection, the value type will be a List with items of the type as specified above.

validation:
  errorMessage
stringThe error message to show when the validation fails.
formatter:
  expression
stringRequired for the `object` type; otherwise, optionalA Jira expression that renders the value as a string. The expression is evaluated with the following context variables:
  • user (User): The current user.
  • issue (Issue): The edited issue.
  • project (Project): The project to which the issue belongs.
  • value: The field's value. The type of this variable depends on the data type of the field and can be one of the following:
    • String, if the data type is string or group.
    • Number, if the data type is number.
    • User, if the data type is user.
    • Map, if the data type is object.
    If the field stores a collection, the value type will be a List with items of the type as specified above.
schemaobjectAllowed only for the `object` typeA JSON schema that desribes values stored in the field.
readOnlybooleanWhether or not the field is read-only. Read-only fields can't be edited by users. Defaults to false.
functionstringA reference to the function module that provides the field rendering. This function must return the CustomField component.
edit:
 function
stringA reference to the function module that provides the field editing experience.
displayConditionsobjectThe object that defines whether or not the field is displayed on the issue view (other views or REST APIs are not affected). See display conditions.

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
jira:customField:
  - key: issue-progress
    name: Issue progress
    description: The progress of the issue, on a scale from 0 to 100.
    type: number
    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

Jira custom field type (beta)

The jira:customFieldType module lets you create a new custom field type in Jira, which lets Jira administrators create new custom fields based on that type.

This module can only be used in Jira company-managed projects.

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.

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 with the dedicated REST API. 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.

Data types

Each field type has to be based on a predefined data type. The data type controls what kind of values the REST API accepts and returns for the field, the field's behavior in JQL, and the default rendering behavior.

Available data types are:

  • string - values represent plain strings. JQL offers autocomplete and exact comparison.
  • number - values represent numbers (double-precision 64-bit IEEE 754 floating points).
  • user - values represent users identified by 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 represent groups identified by names. The field behaves like any other group field in Jira when you interact with it in the UI or the REST API.
  • object - values are arbitrary JSON objects. See below for more details.
Object type

The object type makes use of some additional properties in comparison to other types.

The required formatter property contains a Jira expression that returns a string used to represent the value in places where the rendering function is not supported. For example, the column view in the Global Issue Navigator.

The optional schema property contains the JSON schema that is used to validate values stored in the field.

Here is an example of a field that stores money. It showcases the usage of both the formatter and schema properties:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
  jira:customFieldType:
    - key: cf-type-money
      name: Forge Money Field Type
      description: Field for storing money
      type: object
      formatter: 
        expression: "`${value.amount} ${value.currency}`"
      schema:
        properties:
          amount:
            type: number
          currency:
            type: string
            enum: [ "USD", "EURO", "AUD" ]
        required: [ "amount", "currency" ]

The schema ensures that values of this field look like this:

1
2
3
4
{
  "amount": 100
  "currency": "USD"
}

With the formatter in place, displayed on the issue search, the value will be a string 100 USD.

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 type for fields that store a list of strings, declare it as:

1
2
type: string
collection: list

The following types can be part of a collection:

  • string
  • group
  • user

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

Custom field type lifecycle

This module makes a new custom field type available in Jira. Custom fields of that type can now be created by Jira admins via:

Each field that's created this way has its key set to {extension-key}__{uuid}, where:

  • {extension_key} is the key of the custom field extension defined in the manifest
  • {uuid} is a randomly generated unique identifier

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

The type key of all fields, which is accessible through the schema.custom property in the response of the Get fields REST API, is equal to the exact ID of the custom field type module.

The ID of the custom field type module has the following format ari:cloud:ecosystem::extension/{app-id}/{installation-id}/static/{extension_key}, where:

  • {app-id} is your app ID defined in the manifest.
  • {installation-id} is the ID associated with the app installation, unique for each tenant and environment.
  • {extension_key} is the key of the custom field extension defined in the manifest.

Jira admins can manage fields created this way, just like all other manually created custom fields. The following operations are available:

The fields of the type disappear when the app is uninstalled or if the field type is removed from the manifest. If the app is reinstalled, or the field type is restored, the fields will reappear with the previous data intact.

Configuration

Apps can store configuration information against custom field contexts using the Issue custom field configuration (apps) resource. The app can then access configuration values through Jira expressions or using the Get custom field configurations operation.

For example, you can use configuration details in conjunction with a validation expression to configure maximum and minimum values for a custom number field. To do this, use the Update custom field configurations operation to save a configuration with this shape:

1
2
3
4
{
    "minValue": 0,
    "maxValue": 1000    
}

Then use these configuration items in validation.expression in the manifest definition of the custom field:

1
2
3
4
5
6
7
8
jira:customFieldType:
  - key: cf-type-min-max
    name: Min-max custom field
    description: A field with configurable min/max values
    type: number
    validation:
      expression: "value <= configuration.maxValue && value >= configuration.minValue"
      message: The value is not within the configured bounds

Rendering

Forge apps can optionally provide their own rendering of the fields of the type 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 selected data type, is used if the function is not provided.

Editing

Forge apps can optionally provide their own editing experience of the fields of the type 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 selected data type, is used if the edit function is not provided.

Properties

PropertyTypeRequiredDescription
key

string

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 key of each custom field of this type as described in the Custom field type lifecycle section.

Regex: ^[a-zA-Z0-9_-]+$

namestringYesThe name of the custom field type.
descriptionstringYesThe description of the custom field type.
iconstringThe URL of the icon that's displayed next to the type's name and description.
typestringYesThe type of values stored by fields of this type. Available types are:
  • string
  • number
  • user
  • group
collectionnone|list (default: none) The kind of collection that the field values should be stored in. See collection types for more details.
validation:
  expression
stringA Jira expression that validates the field's value before it's set by the user.

Does not apply when the app updates the value directly with the dedicated REST API.

The expression must return a boolean value.

The expression is evaluated with the following context variables:

  • user (User): The current user.
  • issue (Issue): The edited issue.
  • project (Project): The project to which the issue belongs.
  • configuration: The configuration stored against the custom field context. It will usually be a Map, but it can also be any of the primitive values (number, string, boolean), or a list, depending on what what's the value of the configuration data.
  • value: The value that’s being set on the field. The type of this variable depends on the data type of the field and can be one of the following:
    • String, if the data type is string or group.
    • Number, if the data type is number.
    • User, if the data type is user.
    • Map, if the data type is object.
    If the field stores a collection, the value type will be a List with items of the type as specified above.

validation:
  errorMessage
stringThe error message to show when the validation fails.
formatter:
  expression
stringRequired for the `object` type; otherwise, optionalA Jira expression that renders the value as a string. The expression is evaluated with the following context variables:
  • user (User): The current user.
  • issue (Issue): The edited issue.
  • project (Project): The project to which the issue belongs.
  • configuration: The configuration stored against the custom field context. It will usually be a Map, but it can also be any of the primitive values (number, string, boolean), or a list, depending on what what's the value of the configuration data.
  • value: The field's value. The type of this variable depends on the data type of the field and can be one of the following:
    • String, if the data type is string or group.
    • Number, if the data type is number.
    • User, if the data type is user.
    • Map, if the data type is object.
    If the field stores a collection, the value type will be a List with items of the type as specified above.
schemaobjectAllowed only for the `object` typeA JSON schema that describes values stored in the field.
readOnlybooleanWhether or not fields of this type are read-only. Read-only fields can't be edited by users. Defaults to false.
functionstring A reference to the function module that provides the rendering of fields of this type. This function must return the CustomField component.
edit:
 function
stringA reference to the function module that provides the editing experience for fields of this type.
displayConditionsobjectThe object that defines whether or not the field is displayed on the issue view (other views or REST APIs are not affected). See display conditions.

Example

The following example declares a progress bar custom field type.

1
2
3
4
5
6
7
8
9
10
11
12
jira:customFieldType:
  - key: progress-bar-field-type
    name: Progress bar
    description: A custom field that shows a progress bar.
    icon: https://my-app.com/progress-bar-cf-type-icon
    type: number
    validation:
      expression: value == null || value >= 0 && value <= 100
      errorMessage: Only numbers between 0 and 100 are allowed.
    function: displayProgressBar
    edit:
      function: editProgressBar

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

YesA key for the module, which other modules can refer to. Must be unique within the manifest.

Regex: ^[a-zA-Z0-9_-]+$

functionstringThe 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.
resourcestringA 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.
titlestringYesThe title of the issue action, which is displayed as a menu item.
displayConditionsobjectThe object that defines whether or not a module is displayed in the UI of the app. See display conditions.

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

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.
functionstringThe 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.
resourcestringA 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.
titlestringYesThe title of the issue activity, which is displayed as a tab item.
displayConditionsobjectThe object that defines whether or not a module is displayed in the UI of the app. See display conditions.

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

Yes

A key for the module, which other modules can refer to. Must be unique within the manifest.

Regex: ^[a-zA-Z0-9_-]+$

functionstringThe 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.
resourcestringA 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.
titlestringYesThe title of the issue glance, which is displayed above its label.
labelstringYesThe text shown on the button for the issue glance.
statusobjectThe badge or lozenge shown next to the label. If status is not specified, then no badge or lozenge is shown. See status properties.
displayConditionsobjectThe object that defines whether or not a module is displayed in the UI of the app. See display conditions.

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'

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 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.

Properties

PropertyTypeRequiredDescription
key

string

Yes

A key for the module, which other modules can refer to. Must be unique within the manifest.

Regex: ^[a-zA-Z0-9_-]+$

functionstringThe 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.
resourcestringA 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.
titlestringYesThe 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.
iconstringYesThe 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

boolean

Controls whether or not multiple instances of the issue panel are shown when clicking the issue panel button repeatedly. Defaults to false.

If set to true, a maximum number of five instances of the issue panel can be shown on the issue.

displayConditionsobjectThe object that defines whether or not a module is displayed in the UI of the app. See display conditions.

Jira project page

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.

Properties

PropertyTypeRequiredDescription
key

string

Yes

A key for the module, which other modules can refer to. Must be unique within the manifest.

Regex: ^[a-zA-Z0-9_-]+$

functionstringThe 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.
resourcestringA 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.
titlestringYesThe 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.
iconstringThe URL of the icon that's displayed next to the title. A generic app icon is displayed if no icon is provided.
layoutnative|basic (default: native)The layout of the admin page, which defines the elements that should be displayed on the page (for example, page title).
displayConditionsobjectThe object that defines whether or not a module is displayed in the UI of the app. See display conditions.

Jira workflow validator (beta)

The jira:workflowValidator module creates a workflow validator that can be configured on workflow transitions in company-managed 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 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'
  };
}

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

PropertyTypeRequiredDescription
key

string

Yes

A key for the module, which other modules can refer to. Must be unique within the manifest.

Regex: ^[a-zA-Z0-9_-]+$

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 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.
errorMessagestringThe 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. 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.

Properties

PropertyTypeRequiredDescription
key

string

Yes

A key for the module, which other modules can refer to. Must be unique within the manifest.

Regex: ^[a-zA-Z0-9_-]+$

functionstringThe 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.
resourcestringA 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.
titlestringYesThe title of the macro. In Confluence, this is displayed in the editor.
descriptionstringThe 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.

Scheduled trigger

The scheduledTrigger module repeatedly invokes a function on a scheduled interval. Each trigger is scheduled to start shortly after it is created, about 5 minutes after app deployment. It then runs based on the configured interval hour, day or week.

Every time any changes are made to any scheduled triggers module, all scheduled triggers will be recreated and their start times reset.

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 five scheduled triggers in the manifest.yml file.

Not all invocations for a single scheduled trigger will happen at once. To better improve overall performance, invocations will be distributed evenly across the interval specified on any given module. Distribution is done by installations, so not all installations of an app will have their triggers invoked together. This is however a consistent distribution, meaning that if an hourly trigger invokes at 1:10 for a particular installation, and at 1:20 for another, those installations will invoke again at 2:10 and 2:20 respectively.

There is a small chance of duplicated invocations, such scenarios should be handled in the apps code by the app developer.

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

Properties

PropertyTypeRequiredDescription
key

string

Yes

A key for the module, which other modules can refer to. Must be unique within the manifest.

Regex: ^[a-zA-Z0-9_-]+$

functionstringYesA reference to the function module that defines the behavior.
interval'hour', 'day', 'week'YesThe interval at which to invoke the function.

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

Yes

A key for the module, which other modules can refer to. Must be unique within the manifest.

Regex: ^[a-zA-Z0-9_-]+$

functionstringYesA reference to the function module that defines the behavior.
eventsArray<string>YesA list of product events that trigger the function.

Web trigger (beta)

The webtrigger module invokes a function as the result of an HTTP request.

Within your app, you can programatically obtain the URL to call the web trigger using the web trigger runtime API.

To obtain a web trigger URL for development purposes, run forge webtrigger in the Forge CLI.

Properties

PropertyTypeRequiredDescription
key

string

Yes

A key for the module, which other modules can refer to. Must be unique within the manifest.

Regex: ^[a-zA-Z0-9_-]+$

functionstringYesA reference to the function module that defines the behavior.

Example web trigger URL

1
https://4a6d16a1-bf25-4ddb-9a1a-3a781c11af3d.hello.atlassian-dev.net/x1/XUBR5WnG2Hk2V52APDdGaRSDm

Rate this page: