Jira dashboard background script

The jira:dashboardBackgroundScript module adds an invisible container to the Dashboards page.

Unlike dashboard gadgets, the dashboard background script is not influenced by the dashboard page navigation changes. This makes it the perfect candidate for:

distributing shared data
making heavy calculations
other optimizations

The dashboard background script is only rendered if there is at least one dashboard gadget within the same app present on the dashboard.

Examples

Because modules might be rendered in a different order, it is recommended to handle both scenarios.

Custom UI

Use the events API for communication between dashboard background scripts and dashboard gadgets.

Dashboard background script:

1
2
import { events } from '@forge/bridge';

// Emit the data to already rendered dashboard gadgets
events.emit('app.data-change', 'initial-data');

// Listen to data change requests from dashboard gadgets
events.on('app.request-data', (payload) => {
  events.emit('app.data-change', 'initial-or-changed-data');
});

Dashboard gadget:

1
2
import { events } from '@forge/bridge';

// Request the data in case the dashboard background script is already rendered
events.emit('app.request-data');

// Listen to data change
events.on('app.data-change', (payload) => {
  console.log('The data has changed:', payload)
});

Properties

Property Type Required Description

Property	Type	Required	Description
`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_-]+$`
`resource`	`string`	The dashboard background script module requires a `resource` when building with custom UI.	A reference to the static `resources` entry that the dashboard background script will render. See resources for more details.
`resolver`	`{ function: string }` or `{ endpoint: string }`		Set the `function` property if you are using a hosted `function` module for your resolver. Set the `endpoint` property if you are using Forge remote (preview) to integrate with a remote back end. Can only be set if the module is using the `resource` property.

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_-]+$

resource string The dashboard background script module requires a resource when building with custom UI. A reference to the static resources entry that the dashboard background script will render. See resources for more details.

resolver

{ function: string } or
{ endpoint: string }

Set the function property if you are using a hosted function module for your resolver.

Set the endpoint property if you are using Forge remote (preview) to integrate with a remote back end.

Can only be set if the module is using the resource property.

Extension context

Property	Type	Description
`type`	`string`	The type of the module.