External Widget Development
This topic describes external widget development in Codebeamer.
External widgets are external web applications that are 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.
Codebeamer example Application Configuration
• The following example shows an application configuration for one extension definition file:
"externalWidgetExtensions" :
{ "uri" : "http://localhost:4200/assets/extension.json"
},
• The following example shows an application configuration for multiple extension definition files:
"externalWidgetExtensions" :
[ { "uri" : "http://localhost:4200/assets/extension.json"
},
{
"uri" : "http://localhost:4200/assets/extension2.json"
}
],
• Keep the following in mind regarding cache clearing:
Consider there is a cache for the configuration which has a 10-minute time-to-live, then if you want to see the configuration changes immediately, clear the cache using this endpoint:{YOUR_HOST}/hc/caches/externalWidgetExtensionConfigCache/clear.spr. For example,http://localhost:8080/cb/hc/caches/externalWidgetExtensionConfigCache/clear.spr
External Widget Display Location
There are 3 places where you can place external widgets in Codebeamer:
• In dashboards for users (under the My Start tab), projects (in the project wiki), or trackers(under the Trackers menu)
◦ Root config property: dashboard Widgets
• On item details pages
◦ Root config property:itemDetails Widgets..
• In the document view or document edit view sidebar
◦ Root config property: documentView Widgets
There are 3 places where there are Dashboards in Codebeamer:
• User dashboards under My Start tab.
• Project Wiki dashboards.
• Trackers dashboards under the Trackers menu.
Show or Hide External Widgets with the Enabled Property
The dashboardWidgets@enabled Field is a Boolean field that can be expressed with JSP expression language (JSP EL). If this field evaluates to TRUE in the current dashboard, the widget is available on the Add Widgetwindow.
The expression is evaluated against the current project. On user dashboards, the current project is null. Any ProjectDto attributes such as id, or name 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 is a good candidate for the filtering of external dashboard widgets.
Valid expressions for the Add Widget window.
|
Expression
|
Description
|
|
"enabled": "true"
|
The widget appears in every case
|
|
"enabled": "false"
|
The widget never appears.
|
|
"enabled": "${name eq null}
|
Only applicable for user dashboards
|
|
"enabled": "${name eq 'PTC Software's Default Template'}"
|
Only applicable for the given project (Single quotes must be escaped with a double backslash)
|
|
"enabled": "${(name eq null) or (name eq 'PTC Software's Default Template')}"
|
Applicable for user dashboards and the given project's tracker and project dashboards
|
itemDetailsWidgets@enabled
TheitemDetailsWidgets@enabled is a Boolean field that can be expressed with JSP expression language (JSP EL). If this field evaluates TRUE for the current external widget, the widget is displayed on the item details view among the "Details" section's tabs.
The expression is evaluated against the current item's tracker. Any TrackerDto attributes such as id, name, type and so on can be used.
|
Expression
|
Description
|
|
"enabled": "true"
|
The widget appears for every tracker item
|
|
"enabled": "false"
|
The widget never appears.
|
|
"enabled": "${id == 1337 and name == 'Test' and type == 'Task'}"
|
Tracker attributes used in the expression.
|
The documentViewWidgets@enabled field is used in the same way as the itemDetailsWidgets@enabled field.
Tracker types
The following tracker types can be used in the expression:
"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 Must Be Unique
The 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 window..
The valid config values for them are as follows:
• "all"
• "chart"
• "project"
• "agile"
• "test"
• "personal"
• "other".
Supported External Dashboard Widget Attributes
The following external dashboard widget attributes are supported:
• string—Can also be used for JSON.
• 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 passed to the 3rd party widget app in JSON format.
The following example shows the JSON configuration that is 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 which are linked to the tracker attributes.
Dashboard Icon for Add Widget Pop-up
The dimensions of the dashboard widget icon are 42x42 pixels This icon is shown on the Add Widget window.
Word Export
When a dashboard is exported to Microsoft Word, the exported dashboard does not contain the external dashboard widgets.
Example Configuration (extension.json)
The following code shows an example of an extension.json file.
{
"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": []
}
}
}
}
]
}