Widget Development and Deployment QuickStart Guide

How to write and deploy a custom Widget

Prerequisites

Before starting, make sure that the followings are installed:

• At least Java JDK 1.8 (Oracle or OpenJDK)
• Eclipse IDE, this guide uses Eclipse Luna. Check whether the Eclipse installation has Maven Integration for Eclipse (Maven Integration for Eclipse WTP if required)
• Download the example project from here. Extract the .zip file to a folder.
• Copy the cb.jar file from CODEBEAMER_HOME/tomcat/webapps/cb/WEB-INF/lib/cb.jar to a folder.

Set up the Development Environment

Step 1. Import the project

Open Eclipse and choose the File ► Import... menu option:

Choose Existing Maven Projects, and select the extracted project:

When the import is successful, then the project appears on the left side:

Step 2. Rewrite the path of cb.jar

The Maven build process will download all the dependencies, but the path to cb.jar have to be set manually. Its standard location is CODEBEAMER_HOME/tomcat/webapps/cb/WEB-INF/lib/cb.jar.

Build the code

This example project contains a simple Widget, which has a single field:

And renders this field as text:

First right click on the pom.xml file, and choose Run As ► Maven build...

Type "clean install" into the Goals field and click on [Run].

The console tab should display something like this:

The target directory contains the compiled jar file:

Deploy the Widget

Step 1. Stop the running codebeamer instance

See Stop & Start procedure.

Step 2. Copy the Widget jar file

Copy the jar file created by the Maven build process (demo-widget-0.0.1.jar) to CODEBEAMER_HOME/tomcat/webapps/cb/WEB-INF/lib.

Step 3. Start the codebeamer instance

See You must login to see this link. Register now, if you have no user account yet.

Step 4. Verify that the Widget is deployed

When properly deployed, the Widget shows up in the proper category on Widget Browser:

Troubleshooting & Important Notes

i18n of labels

Every widget needs a couple of labels to render properly which need to be specified in the my-ApplicationResources.properties file inside the src/main/resources folder. See Widget Development Documentation for more details

Our recommended format for name and description:

• dashboard.X.widget.name - Widget's name label on Widget Browser.
• dashboard.X.widget.short.description - Widget's description on Widget Browser.

Mandatory format for attribute labels:

• widget.editor.field.label.X

If the my-ApplicationResources.properties file is already in use for other purposes, merge the widget-related labels into that file! (Its expected location is CODEBEAMER_HOME/tomcat/webapps/cb/WEB-INF/lclasses)

Widget not recognized

codebeamer application uses Spring annotations to discover Widgets. If the widget does not show up in the Widget Browser, then double check these:

• Widget class and constructor of Widget class have the Jackson annotations like in the demo project.
• WidgetInformation class has @Component annotation.
• Renderer classes have @Component annotation and a unique @Qualifier.
• Constructor of Renderer classes have @Autowired annotation.
• WidgetFactory class has @Component annotation and a unique @Qualifier.
• Constructor of Renderer classes have @Autowired annotation. Renderer parameters reference the correct @Qualifiers.
• getInjectableValues method in WidgetFactory class use the same identifiers as @JacksonInject annotations on the Widget constructor.

Widget not available

Custom widgets for codebeamer are currently not supported on codebeamer X.

If a Dashboard contains a Widget, which is not present in the system, then codebeamer shows the following error:

Double check that the correct jar file is in CODEBEAMER_HOME/tomcat/webapps/cb/WEB-INF/lib.