Jira dashboard items

This page describes how to migrate a Jira dashboard item module from Connect to the Forge gadget module.

As a prerequisite, please refer to the parent page that contains a general guide on how to migrate Jira modules from Connect to Forge.

Configuration

A Connect app is free to decide where to store the item’s configuration. However, dashboard item properties are suggested to be used.

In contrast to Connect, a Forge dashboard gadget stores the configuration automatically by submitting the edit form that is rendered when the gadget is configured by the user. The configuration is stored as dashboard item properties and provided within the context on every render.

After the migration, the Forge app can easily access the old Connect configuration if it was stored as dashboard item properties, either via REST API or via the context object passed to the app on every render.

Example

Let's assume that our Connect app stored its configuration using dashboard item properties, under the itemkey key. After the migration, the Forge app starts using an additional property with a name key.

We can list dashboard item properties using a REST API call:

GET {{baseUrl}}/rest/api/3/dashboard/:dashboardId/items/:itemId/properties

1
2
{
    "keys": [
        {
            "key": "itemkey",
            "self": "{{baseUrl}}/rest/api/3/dashboard/:dashboardId/items/:itemId/properties/itemkey"
        },
        {
            "key": "name",
            "self": "{{baseUrl}}/rest/api/3/dashboard/:dashboardId/items/:itemId/properties/name"
        }
    ]
}

To get the value of the itemkey property we should call:

GET {{baseUrl}}/rest/api/3/dashboard/:dashboardId/items/:itemId/properties/:propertyKey

1
2
{
  "key": "itemkey",
  "value": {
    "project": "10000",
    "title": "Connect Dashboard Item migration example"
  }
}

The same properties are passed within the context object to the Forge module on every render. We can extract them using following snippet:

1
2
const View = () => {
  const { extensionContext: { gadgetConfiguration } } = useProductContext();

  console.log(gadgetConfiguration);

  return (
    <DashboardGadget>
      <Text
        content={`Hello ${gadgetConfiguration.name || "world"}.`}
      />
    </DashboardGadget>
  );
};

gadgetConfiguration object contains following properties:

1
2
{
  "name": "Forge Dashboard Gadget",
  "itemkey": { 
    "project": "10000", 
    "title": "Connect Dashboard Item migration example"
  }
}

It's important to keep in mind, if the Forge module uses the same entity property key for its properties as the Connect module did, the old configuration will be overridden after the first gadget configuration.

Limitations and differences

Forge dashboard gadgets offer a similar feature set as Connect dashboard items. However, please be mindful of the following limitations:

• The Forge dashboard item module doesn’t have a configurable property. Instead, the gadget configuration experience is provided by the function/resource specified in the edit property in the manifest.yml file, rather than the onDashboardItemEdit callback used in Connect. If an edit function/resource is not provided, the gadget is not configurable.
• Currently, there is no equivalent for the setDashboardItemTitle method in Forge. You can set the dashboard item title using the title property of the Forge dashboard item module in the manifest.yml file.

Many-to-one migration

It's also possible to migrate multiple Connect dashboard items to a single Forge gadget. It might be useful when the Connect dashboard items are similar and the Forge gadget could replace all of them; or when the Forge gadget consolidates the functionality of multiple Connect dashboard items. In such a case, the Forge gadget will replace every instance of different types of the Connect dashboard items on every dashboard it was configured on.

To achieve that, in manifest.yml specify the list of Connect module keys that should be migrated to the Forge gadget. The Forge gadget key doesn't need to be the same as any of the migrated Connect module keys. Jira will use only the connectKeys list when searching for modules that should be replaced.

Example:

1
2
modules:
  jira:dashboardGadget:
    - key: forge-gadget-module
      title: Many to one migration gadget
      description: Many to one migration gadget
      thumbnail: https://developer.atlassian.com/platform/forge/images/icons/issue-panel-icon.svg
      function: main
      edit:
        function: edit
      connectKeys:
        - connect-dashboard-item-module-1
        - connect-dashboard-item-module-2
        - connect-dashboard-item-module-3
# ...
app:
  id: ari:cloud:ecosystem::app/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
  connect:
    key: connect-dashboard-item-app
    remote: connect
# ...
connectModules:
   jira:jiraDashboardItems:
     - name:
         value: Connect dashboard item 1
         i18n: issues.in.project.i18n
       url: >-
         /issues-in-project?dashboard={dashboard.id}&dashboardItem={dashboardItem.id}
       key: connect-dashboard-item-module-1
       description:
         value: Connect dashboard item 1
         i18n: issues.in.project.description.i18n
       thumbnailUrl: /thumbnail
       configurable: true
     - name:
         value: Connect dashboard item 2
         i18n: issues.in.project.i18n
       url: >-
         /issues-in-project?dashboard={dashboard.id}&dashboardItem={dashboardItem.id}
       key: connect-dashboard-item-module-2
       description:
         value: Connect dashboard item 2
         i18n: issues.in.project.description.i18n
       thumbnailUrl: /thumbnail
       configurable: true
     - name:
         value: Connect dashboard item 3
         i18n: issues.in.project.i18n
       url: >-
         /issues-in-project?dashboard={dashboard.id}&dashboardItem={dashboardItem.id}
       key: connect-dashboard-item-module-3
       description:
         value: Connect dashboard item 3
         i18n: issues.in.project.description.i18n
       thumbnailUrl: /thumbnail
       configurable: true