Bitbucket modules
Common modules
Compass modules
Confluence modules
Jira modules
Jira Service Management modules

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

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 dashboard gadget 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 dashboard gadget. This function must return the DashboardGadget component.
resourcestringA reference to the static resources entry that the dashboard gadget displays. See resources for more details.
render'native'Yes for UI Kit 2Indicates if the module is a UI Kit 2 module.
resolver{ function: string } or
{ endpoint: string }
Yes

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.

titlestring or { text: string, href: string }YesCan be:
  • a plain string containing the gadget's title.
  • an object containing a text property containing the gadget's title and a href property containing a link that the user is sent to when they click the gadget’s title.
descriptionstringYesA description of what the gadget does.
thumbnailstringYesThe absolute URL of the icon that's displayed next to the gadget's name and description in the list of gadgets that can be added to a dashboard.
edit:
 function
stringA reference to the function module that provides the editing experience for dashboard gadgets.
edit:
 resource
stringA reference to the static resources entry that provides the editing experience for dashboard gadgets. See Resources for more details. To submit the view, use the submit API.
edit:
 render
'native'Indicates if your editing experience should display as UI Kit 2.
refreshablebooleanSet the refreshable property of the dashboard item to false to override the native Jira refresh behavior.

Extension context

PropertyTypeDescription
gadgetConfigurationobjectObject containing gadget configuration.
dashboard:
id
stringID of the dashboard.
gadget:
id
stringID of the gadget.
typestringThe type of the module.

Rate this page: