Jira dashboard gadget

The jira:dashboardGadget module creates a dashboard gadget that is displayed on the Dashboards page.

This module can be used in Jira Work Management, Jira Software, and Jira Service Management.

See the DashboardGadget component documentation for an example.

Configuration

Dashboard Gadgets can be configured using their edit mode.

Auto-refresh

Dashboard Gadgets can be refreshed manually by your users and automatically. The automatic refresh interval (in minutes) is configured by submitting a refresh field as part of an edit view (the API accepts positive integers for this field).

UI kit

When using the onSubmit method in the DashboardGadgetEdit UI kit component, provide a refresh field to the object returned by your onSubmit function.

1
2
const onSubmit = () => ({ ...otherFieldsToSubmit, refresh: 15 });

Custom UI

When using Custom UI to work with the Dashboard Gadget module, use the submit API as part of your edit view to provide a refresh field to the submit function:

1
2
await view.submit({ ...otherFieldsToSubmit, refresh: 15 });

Overriding default gadget refresh behavior

1. Set the refreshable property to false in the gadget's manifest file.
2. Write your own refresh logic by handling the JIRA_DASHBOARD_GADGET_REFRESH event using the events.on() function from the Forge bridge.
3. Optionally, apply the refresh logic only when the origin and gadgetId properties of the payload satisfy a condition.

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

function App() {
  useEffect(() => {
    const subscription = events.on('JIRA_DASHBOARD_GADGET_REFRESH', (payload) => {
      // the payload contains the following properties:
      // - payload.origin - either 'dashboard' or 'gadget' depending on which refresh button was clicked
      // - payload.gadgetId - the ID of the gadget initiating the refresh (only available if payload.origin === 'gadget')

      // you can obtain the ID of the currently rendered gadget using the view.getContext() function
    });

    return () => {
      subscription.then(({ unsubscribe }) => unsubscribe());
    };
  }, []);

  // render the gadget
}

When the user clicks the refresh button of any Forge dashboard gadget that has overridden the default refresh behavior, the JIRA_DASHBOARD_GADGET_REFRESH event will be triggered and all Forge gadgets will receive it. You can limit the scope of the refresh logic based on the available payload, for example with payload.origin === 'dashboard' || payload.gadgetId === thisGadgetId.

Conditional rendering

With Custom UI, you can define the same resource for viewing and editing your dashboard gadget.

First, define your manifest:

1
2
# manifest.yml
modules:
  jira:dashboardGadget:
    - key: hello-world-gadget
      title: Hello world!
      description: A hello world dashboard gadget.
      thumbnail: https://developer.atlassian.com/platform/forge/images/icons/issue-panel-icon.svg
      resource: main # the resource used to view our dashboardGadget
      resolver:
        function: resolver
      edit:
        resource: main # the same resource, used to edit our dashboardGadget configuration
resources:
  - key: main
    path: static/hello-world/build

Then in your Custom UI, use the view API to determine whether to display the view mode or edit mode:

1
2
// App.jsx
import React, { useEffect, useState } from 'react';
import { view } from '@forge/bridge';
import View from './View';
import Edit from './Edit';

function App() {
  const [context, setContext] = useState();

  useEffect(() => {
    view.getContext().then(setContext);
  }, []);

  if (!context) {
    return 'Loading...';
  }

  return context.extension.entryPoint === 'edit' ? <Edit/> : <View/>;
}

export default App;

Properties

Extension context