External Widget Development

This page describes external widget development in codebeamer.

Introduction

External widgets are external web applications registered into codebeamer to provide information and functionality in a context sensitive and configurable way.

Currently, external widgets can be used to provide:

• Configurable dashboard widgets.
• Item-dependent document view side-panels.
• Additional item detail tabs.

CB example Application Configuration

• One extension definition file:
  

  "externalWidgetExtensions" : {
      "uri" : "http://localhost:4200/assets/extension.json"
  },
  

• Multiple extension definition files:
  

  "externalWidgetExtensions" : [
          {
              "uri" : "http://localhost:4200/assets/extension.json"
          },
          {
              "uri" : "http://localhost:4200/assets/extension2.json"
          }
      ],
  

• Cache Clearing
  • There is a cache for the configuration with a 10-minute "time to live".
  • To see the configuration changes immediately, clear the cache with this endpoint: {YOUR_HOST}/hc/caches/externalWidgetExtensionConfigCache/clear.spr
  • For example http://localhost:8080/cb/hc/caches/externalWidgetExtensionConfigCache/clear.spr

Places where external widgets can be displayed

There are 3 places where you can place external widgets in codebeamer:

• Dashboards (User / Project / Trackers)
  • root config property: dashboardWidgets
• Item Details page
  • root config property: itemDetailsWidgets
• Document view / Document Edit view sidebar.
  • root config property: documentViewWidgets

There are 3 places where are Dashboards in codebeamer:

• User dashboards under My Start.
• Project WIki dashboards.
• Trackers dashboards under the Trackers menu.

Show/hide external widgets with enabled property

dashboardWidgets@enabled

This is a boolean field that can be expressed with JSP expression language (JSP EL). If this field evaluates true to the current dashboard, the widget will be available on the Add Widget pop-up.

The expression will be evaluated against the current project. On user dashboards, the current project is null. Any ProjectDto attributes (e.g., id, name, etc.) can be used.

Since the project's name is unique and the id can change when using Project Configuration Deployment from a source system to a target, writing an expression to the name could be a good candidate to filter external dashboard widgets.

Valid expressions for the Add Widget pop-up:

• "enabled": "true" - widget will appear in every case
• "enabled": "false" - widget will never appear
• "enabled": "${name eq null} " - only for user dashboards
• "enabled": "${name eq 'Intland Software's Default Template'}", - only for the given project (single quotes have to be escaped with a double backslash)
• "enabled": "${(name eq null) or (name eq 'Intland Software's Default Template')}", - for user dashboards and the given project's dashboards (project and tracker)

itemDetailsWidgets@enabled

This is a boolean field that can be expressed with JSP expression language (JSP EL). If this field evaluates true to the current external widget, it will be displayed on the item details view among the "Details" section's tabs.

The expression will be evaluated against the current item's tracker. Any TrackerDto attributes (e.g., id, name, type, etc.) can be used.

• "enabled": "true" - widget will appear for every tracker item
• "enabled": "false" - widget will never appear
• "enabled": "${id == 1337 and name == 'Test' and type == 'Task'}" - tracker attributes used in expression

Tracker types

"Area", "Bug", "Change Request", "Component", "Configuration Item", "Contact", "Epic", "Issue", "Platform", "Release", "Requirement", "Risk", "RPE Report", "Task", "Team", "Testcase", "Testconf", "Testrun", "Testset", "Work Log" (aka.: Time Recording), "User Story"

documentViewWidgets@enabled

Same as itemDetailsWidgets@enabled.

Widget IDs Need to Be Unique

externalWidgetConfig@id needs to be unique (even across multiple extension JSON files), otherwise, the configuration will be overwritten from another config with the same id.

Categories of Dashboard Widgets

Several categories are listed on the Add Widget pop-up.

The valid config values for them are:

• "all"
• "chart"
• "project"
• "agile"
• "test"
• "personal"
• "other".

Supported External Dashboard Widget Attributes

• string - can be used for JSON too.
• tracker- a single tracker can be selected.
  • this generates a project selector for itself.
  • the selected project is passed to the 3rd party widget app with the following name: "{trackerFieldName}-projectId".
• trackerList- multiple trackers can be selected.
  • this generates a project selector for itself.
  • the selected project is passed to the 3rd party widget app with the following name: "{trackerFieldName}-projectId".
• project - a single project can be selected.
• projectList - multiple projects can be selected.

The values of the attributes are getting passed to the 3rd party widget app in JSON format.

• Example JSON config passed to the 3rd party widget app:
  

  {
    "someText": "lorem ipsum dolor",
    "trackerId": [
      4870
    ],
    "trackerId-projectId": [
      4
    ],
    "trackerId2": [
      4612
    ],
    "trackerId2-projectId": [
      3
    ]
  }
  

The keys come from the extension configuration json, except for the projectIds that are linked to the tracker attributes.

Dashboard Icon for Add Widget Pop-up

The dimensions of the dashboard widget icon are 42x42px. This will be shown on the Add Widget pop-up.

Word Export

The exported dashboard does not contain the External Dashboard widgets.

An example configuration (extension.json)

{
  "documentViewWidgets": [
    {
      "enabled": "${id == 1337 and name == 'Test' and type == 'Task'}",
      "externalWidgetConfig": {
        "id": "test-widget-1",
        "name": "Test Widget",
        "viewUrl": "http://localhost:4200/",
        "iconUrl": "http://localhost:4200/assets/cog.png"
      }
    },
    {
      "enabled": "false",
      "externalWidgetConfig": {
        "id": "test-widget-2",
        "name": "Test Widget",
        "viewUrl": "http://localhost:4200/",
        "iconUrl": "http://localhost:4200/assets/cog.png"
      }
    }
  ],
  "itemDetailsWidgets": [
    {
      "enabled": "true",
      "externalWidgetConfig": {
        "id": "test-widget-3",
        "name": "Test Widget",
        "viewUrl": "/",
        "iconUrl": "/assets/cog.png"
      }
    }
  ],
  "dashboardWidgets": [
    {
      "enabled": true,
      "externalWidgetConfig": {


        "id": "test-dashboard-widget",
        "name": "Test Dashboard Widget",
        "shortDescription" : "test external dashboard widget",
        "category" : "other",
        "knowledgeBaseUrl" : "http://localhost:4200/knowledgeBase",
        "viewUrl": "/",
        "iconUrl": "/assets/cog.png",
        "attributes": {
          "someText": {
            "typeName": "string",
            "fieldLabel": "Some Text",
            "required": true,
            "value": "aaa"
          },
          "trackerId": {
            "typeName": "tracker",
            "fieldLabel": "Tracker Custom Label",
            "required": true,
            "value": []
          },
          "trackerIdList": {
            "typeName": "trackerList",
            "fieldLabel": "Tracker List Custom Label",
            "required": true,
            "value": []
          },
          "projectId": {
            "typeName": "project",
            "fieldLabel": "Project Custom Label",
            "required": true,
            "value": []
          },
          "projectIdList": {
            "typeName": "projectList",
            "fieldLabel": "Project List Custom Label",
            "required": true,
            "value": []
          }
        }
      }
    }
  ]
}

Diagrams

Simplified Integration

For simple operations when there is no need for external backend:

Advanced Integration

Sequence Diagrams

General Workflow

Details:

1. User navigates to the Document View of a tracker.
   • On the Document View, the External Widget can be displayed on the right hand side side-panel.
2. Document View renders the IFrame.
   • The External Widget is encapsulated into an IFrame.
3. The IFrame invokes the viewUrlof the widget.
   • The IFrame tries to load the widget UI from the viewURL provided during the widget configuration on codebeamer.
4. External widget instantiation
5. Get Authentication token
6. Authentication token
7. Get Config
8. External Widget Config
9. Get Base URL
10. Rest API V3 URL
11. Set Widget Height
12. Widget Backend initialization
13. Backend Instance
14. Get Selected Item
15. Item Id
16. Get Item details
17. Get Item details from codebeamer
18. Item details
19. Additional calculations / External Service calls
20. Item details
21. Result Widget HTML
    • The widget HTML is filled with the corresponding item details based on the needs.
22. Display Document View
    • The user can see the correctly filled External Widget for the selected item on the right side-panel.

Selected Item Has Been Changed on codebeamer

Use Case: The user changes the selected item, for example, on the Trackers Dashboard, thus the External Widget content shall be updated.

Details:

1. Widget creates a callback to be notified about Item selection changes
2. Widget registers the callback on the CB Frontend
3. User changes the Item selection
4. The CB Frontend notifies the External Widget through the registered callback
5. Registers new Item Id internally
   • Modifies the selected Item Id stored on widget side.
6. Get Item details
7. Get Item details from CB
8. Item details
9. Additional calculations / External Service calls
   • The widget backend can make additional operations; it can use own database or even invoke external services which could be necessary for the External Widget operations.
10. Item details
11. Updated Widget HTML
    • The widget HTML is changing based on the changed Item details.
12. Display updated Document View page
    • The user can see the updated External Widget Content belongs to the selected Item on CB.

Reload an item in CB

Use Case: The user modifies some property of an item on the External Widget UI. This modification shall be updated in CB.

Details:

1. User makes Item modifications on External Widget.
   • External widgets can be used for Item updates also. Theoretically, everything is possible which is supported by the Rest API V3.
2. Modification request
   • Modification request sent from the widget frontend to the widget backend (e.g., POST HTTP request).
3. Corresponding update method
   • The Backend shall invoke the corresponding update/... method on the Swagger client (which will invoke the corresponding Rest API V3 endpoint).
4. Update result
   • The update result is the same as in case of the Swagger Client. It is up to the External Widget implementation, how to handle and display a failed update for example.
5. Additional calculations / External Service calls
   • The widget backend can make additional operations, it can use own database or even invoke external services which could be necessary for the External Widget operations.
   • For example, in case of a successful update, the same modifications can be done in different external systems or in own databases.
6. Result of the update
   • The backend of the widget notifies the frontend about the update result.
7. Reload Item request
   • Based on the update result, the External Widget can request an Item reload from the CB UI.
8. Reload Item on CB UI
   • If the given page supports this Item reload functionality, CB reloads the given item from the DB.
9. Refresh Document View with updated Item
   • The user can see the modifications done on the External Widget in the CB application.

External Widget Deployment

• In theory, the External widget can be any external web application from the internet which can be included into an IFrame with its URL.
• The current approach for the External Widget deployment is a separate docker container, therefore, every External Widget have its own lightweight docker container.

Demo applications

Angular application

https://github.com/intland/external-widget-angular-example

Typescript application

https://github.com/intland/external-widget-typescript-example

Javascript application

https://github.com/intland/external-widget-simple-example