The dashboards:widget and dashboards:backgroundScript modules are generally available for new Jira dashboards and replace the legacy jira:dashboardGadget and jira:dashboardBackgroundScript modules.

If you don't already see the dual-create option on your Jira development or test site, you can enroll the site in the Developer Canary Program to enable creation of either a classic Jira dashboard or a new dashboard. For rollout, migration, and deprecation details, see the Jira Dashboards announcement.

The Dashboard UI bridge is a JavaScript API that enables Forge dashboard widgets to securely integrate with Jira dashboards. It also exposes the filter APIs for apps that define filters for dashboards.

Install the Dashboard UI bridge using the @forge/dashboards-bridge npm package. Import @forge/dashboards-bridge using a bundler, such as Webpack.

You can start by creating a new app from one of the Custom UI templates. In the static/hello-world directory, run npm install && npm build to bundle the static web application template with the Dashboard UI bridge into the static/hello-world/build directory. Use this directory as the resource path in the Forge app's manifest.yml.

In the template, use the bridge in static/hello-world/src/View.js like this:

1
2
3
4
5
6
7
8
import { widget } from "@forge/dashboards-bridge";

// Set preview configuration for widget picker
widget.setPreviewConfig({
  title: "My Widget Preview",
  description: "Preview description",
});

For widget edit functionality, use the bridge in static/hello-world-edit/src/Edit.js like this:

1
2
3
4
5
6
7
8
9
10
11
12
import { widgetEdit } from "@forge/dashboards-bridge";

// Handle save events
widgetEdit.onSave(async (config, { widgetId }) => {
  console.log("Widget saved!", config, widgetId);
});

// Handle product save events
widgetEdit.onProductSave(async (config) => {
  return config; // Return config to save in product
});

For dashboard filter functionality, use the bridge in your filter resource like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import { filter } from "@forge/dashboards-bridge";

filter.onProductSave(async () => ({
  operator: "AND",
  groups: [
    {
      label: "Status",
      comparison: "EQUALS",
      defaultValues: ["Done"],
      dimensions: ["status"],
    },
  ],
}));