1Widget Development and Deployment QuickStart Guide

1.1How to write and deploy a custom Widget

1.1.1Prerequisites

Before starting, make sure that the following are installed:

• At least Java JDK 1.8 (Oracle or OpenJDK).
• Eclipse IDE, this guide uses Eclipse Luna. Check whether the Eclipse installation has Eclipse Maven Integration.
• 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.

1.1.2Set up the Development Environment

1.1.2.1Step 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:

1.1.2.2Step 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.

1.1.3Build 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:

1.1.4Deploy the Widget

1.1.4.1Step 1. Stop the running codebeamer instance

See Starting/Stopping Codebeamer.

1.1.4.2Step 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.

1.1.4.3Step 3. Start the Codebeamer instance

See Starting/Stopping Codebeamer.

1.1.4.4Step 4. Verify that the Widget is deployed

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

1.1.5Troubleshooting & Important Notes

1.1.5.1i18n 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)

1.1.5.2Widget 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.

1.1.5.3Widget 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.