Tags: External Widget Development

Getting Started with External Widgets

This page demonstrates the set up and development of a minimal external widget to bootstrap development.

Prerequisites

Set up a directory where all the external widget files will reside. This directory is independent of codebeamer.

Descriptor JSON

An external widget application can define multiple external widgets to be consumed by codebeamer. These widgets and their properties are defined in a JSON file which will be served by an HTTP server. This way, new widgets can be defined or existing ones can be reconfigured without touching codebeamer.

For the full documentation, see External Widget API reference.

Create an extension.jsonfile with the following minimal configuration:

{
  "dashboardWidgets": [
    {
      "enabled": "true",
      "externalWidgetConfig": {
        "id": "dashboard-widget-example",
        "name": "Dashboard Widget Example",
        "viewUrl": "./index.html",
        "attributes": {
        }
      }
    }
  ]
}

The most important property is the viewUrl which defines the exact URL that will be loaded inside the IFrame. This URL will be resolved relative to the URL of the JSON configuration.

Run a web server which serves the contents of the directory via HTTP
- For example, create the following docker-compose.yml file, and run it via $ docker compose up:
```
version: "3.9"
services:
  nginx:
    image: nginx
    volumes:
      - .:/usr/share/nginx/html:ro
    ports:
      - "1903:80"
```
- Make sure the configuration is available at http://localhost:1903/extension.json.

Technically it is also possible to run the external widget as additional web application in the Tomcat used to run codebeamer, but this approach is discouraged as bypass the isolation of the external widget from codebeamer.

Additional examples for Document View and Item Details View external widgets

{
  "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": "true",
      "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"
      }
    }
  ]
}

You can set up all three types of external widgets in one descriptor file.

Find a complex example here: External Widget Development

codebeamer Configuration

To load the external widget into a codebeamer instance, specify the following property in System Admin ► Application configuration:
```
"externalWidgetExtensions" : {
    "uri" : "http://localhost:1903/extension.json"
}
```
- To load multiple external widget configuration endpoints, the URLs can be specified as an array:
```
"externalWidgetExtensions" : [
    {
        "uri" : "http://localhost:1903/extension.json"
    },
    {
        "uri" : "https://example.com/assets/extension.json"
    }
],
```
- Note that the codebeamer backend should be able to fetch the contents of this URL. The fact that it is reachable via the browser may not be enough.
- The widget configuration is cached for 10 minutes by default.
  - To clear the cache, open {CODEBEAMER_CONTEXT}/hc/caches/externalWidgetExtensionConfigCache/clear.spr
If the configuration is applied properly, the next time a user would like to add a new widget to a dashboard page, the external widget should show up on the list under tab Other.
- If the configuration is not loaded or the widget is not showing up in the list, see the codebeamer logs.

IFrame Integration Client Library

Intland provides a javascript/typescript frontend library to allow the application running inside the IFrame to interact with the codebeamer UI. The library uses the postMessage API internally.

Simple Example

The below example showcases a minimal setup which is necessary to interact with codebeamer via the widget API and through the Swagger API. It shows the list of projects the user has access to.

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

Download and extract the client library from https://registry.npmjs.org/@intland/cb-widget-api/-/cb-widget-api-0.1.0.tgz
- To grab the URL of the latest version, run npm show @intland/cb-widget-api
Move and rename the ./package/dist/index.js file to ./cb-widget-api.js
Create an index.js file which will contain the script.

Create an index.html file which loads both scripts in order:

<!doctype html>
<html lang="en">
<body>
<script src="cb-client.js"></script>
<script src="index.js"></script>
</body>
</html>

The library will be exposed as a global on the browser window object, therefore, inside the index.js, the API class can be accessed in the following way:
```
const api = new window.CbWidgetApi.WidgetApi(window, 'unique-widget-id', '*');
```
To fetch the list of projects through the Swagger API, a JWT token is needed. The external widget API exposes this functionality via the authenticate function, which requests a valid token on the codebeamer side and returns it as a Promise:
```
api.authenticate().then(response => console.log(response.token));
```

With the token, a request can be issued through the swagger API:

api.authenticate()
    .then(response => response.token)
    .then(token => fetch('http://localhost:8080/cb/api/v3/projects', {
        headers: {
            authorization: 'Bearer ' + token
        }
    }))
    .then(response => response.json())
    .then(projects => console.log(projects));

If the widget is configured properly in codebeamer when the user adds it to a dashboard, it should now log the accessible projects to the development console.

Typescript Support

The library itself is also written in typescript, therefore, typing information is bundled in the npm package.

For the sake of simplicity, the previous widget will be created in this example using Parcel, but any popular bundler (e.g., Webpack as used by Angular or Create React App) should be compatible.

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

Prerequisites: Node.js and npm need to be installed.

In the prepared directory, create a new package.json file: $ npm init
Install parcel, and the @intland/cb-widget-api - package:
```
$ npm install parcel @intland/cb-widget-api --save
```

Create an index.ts script:

import {WidgetApi} from "@intland/cb-widget-api";

const api = new WidgetApi(window, 'widget-id', '*');
api.authenticate().then(response => response.token)
    .then(token => fetch('http://localhost:8080/cb/api/v3/projects',{
        headers: {
            authorization: 'Bearer ' + token
        }
    }))
    .then(response => response.json())
    .then(projects => console.log(projects));

Create an index.html file to load it:

<!doctype html>
<html lang="en">
<body>
<script type="module" src="index.ts"></script>
</body>
</html>

Running the $ npx parcel index.html should serve the application on localhost:1234
Optional: Serve extension.json via parcel for development.
- Install $ npm install -D parcel-reporter-static-files-copy
- Create a .parcelrc file with the following configuration:
```
{
  "extends": ["@parcel/config-default"],
  "reporters":  ["...", "parcel-reporter-static-files-copy"]
}
```
- Put the extension.json file under a new ./static directory.
- Running the $ npx parcel index.html next time, the widget configuration should be available at http://localhost:1903/extension.json
After configuring this widget in codebeamer, it should behave the same way as in the simple example.