Getting Started with External Widgets
This topic demonstrates the set up and development of a minimal external widget to bootstrap development.
Prerequisites
As a prerequisite, 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 is served by an HTTP server. This way, new widgets can be defined, or existing widgets can be reconfigured without touching Codebeamer.
For the full documentation, see External Widget API reference.
1. Create an extension.json file containing 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 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.
|
2. Run a web server which serves the contents of the directory using 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"
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.
It is also possible to run the external widget as an additional web application in the Tomcat that is used to run Codebeamer, but this approach is discouraged because it bypasses the isolation of the external widget from Codebeamer.
Additional Examples for Document View and Item Details View External Widgets
This section contains 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, complete the following steps:
1. Specify the following property in > :
"externalWidgetExtensions" : {
"uri" : "http://localhost:1903/extension.json"
}
"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"
}
],
{
"uri" : "http://localhost:1903/extension.json"
},
{
"uri" : "https://example.com/assets/extension.json"
}
],
|
|
The Codebeamer backend must be able to fetch the contents of this URL. The fact that the URL is reachable through the browser may not be enough. The widget configuration is cached for 10 minutes by default.
|
To clear the cache, open the following file {CODEBEAMER_CONTEXT}/hc/caches/externalWidgetExtensionConfigCache/clear.spr
2. The next time a user adds a new widget to a dashboard page, the external widget appears in the list under 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
Codebeamer provides a javascript/typescript frontend library to allow the application running inside the IFrame to interact with the Codebeamer user interface. The library uses the postMessage API internally.
Simple Example
The following example shows a minimal setup to interact with Codebeamer using the widget API and the Swagger API. It shows the list of projects the user has access to.
The example project is available at the following URL:https://github.com/intland/external-widget-simple-example
To display the list of project to which the user has access, complete the following steps:
1. Download and extract the client library from the following location: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
2. Move and rename the ./package/dist/index.js file to the following location and name ./cb-widget-api.js
3. Create an index.js file to contain the script.
4. Create an index.html file to load both scripts in order, as follows:
<!doctype html>
<html lang="en">
<body>
<script src="cb-client.js"></script>
<script src="index.js"></script>
</body>
</html>
<html lang="en">
<body>
<script src="cb-client.js"></script>
<script src="index.js"></script>
</body>
</html>
5. The library is exposed as a global on the browser window object. As a result, inside the index.js, the API class can be accessed as follows:
const api = new window.CbWidgetApi.WidgetApi(window, 'unique-widget-id', '*');
6. To fetch the list of projects through the Swagger API, a JWT token is needed. The external widget API exposes this functionality through the authenticate function, which requests a valid token on the Codebeamer side and returns it as a response:
api.authenticate().then(response => console.log(response.token));
7. With the token from the previous step, a request can be issued through the Swagger API as follows:
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));
.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));
8. If the widget is configured properly in Codebeamer when the user adds it to a dashboard, it now logs the accessible projects to the development console.