How to build your own tool for the WAS Liberty Admin Center.
Before you begin:
- Download and install WAS Liberty (WAS Liberty V126.96.36.199 Runtime or later; or the latest Beta Runtime) with the WebSphere Developer Tools (WDT) for Eclipse.
- Create a server called
You will need network access to run this walk-through as it downloads features from the remote Liberty Repository.
Install the WAS Liberty Admin Center feature
The Admin Center is an optional feature in Liberty, and so needs to be installed either via the WebSphere Developer Tools (WDT) tools or the command line
To install the Admin Center feature from WDT:
- In the Runtime Explorer view in Eclipse, right-click the Liberty instance (by default labelled
WebSphere Application Server Liberty Profile [installation location]), then click Install Add-on….
- In the filter box of the Liberty Add-ons dialog, type
Admin Centerto display the Admin Center feature in the window.
- Click the Install button for the Admin Center feature and the button label changes to Install Pending.
- Click Next and follow the rest of the wizard, ensuring that the installation directory is correct.
The AdminCenter feature should now install.
To install the Admin Center feature from the command line:
- Change to your Liberty installation location; e.g.
- Enter the following command:
featureManager install adminCenter-1.0
Configuring the server with the Admin Center feature and required security
These instructions show how to set up a standalone server running the Admin Center. If you want to configure a collective with the Admin Center, please follow the instructions in the Knowledge Center on Admin Center collective configuration.
- In the Servers view of Eclipse, expand the server and double-click the Server Configuration [server.xml] element.
- Click Feature Manager in the Configuration Structure pane. The Feature Manager configuration is displayed in the right-hand side of the panel, showing that the
jsp-2.2feature is enabled on the server.
- Click Add… by the Feature table, and choose adminCenter-1.0 from the dialog, then click OK. The Admin Center feature is now listed along with the jsp-2.2 feature in the Server Configuration editor.
- Now click the Server Configuration element in the Configuration Structure pane and click Add….
- Select Quick Start Security, then click OK to add it to the configuration. You should now see User name and User password fields in the Quick Start Security configuration on the right-hand side of the editor.
admininto the User name field, and
adminpwdinto the Password field.
- Now click the Server Configuration element again and add the Keystore element.
- In the editor, click the Keystore element, then enter
libertyin the Password field in the right-hand side of the panel. Leave all other field values as they are.
- Save this configuration change and close the editor.
- Start the server: in the Servers view, right-click defaultServer > Start.
- To access the Admin Center, click the URL
http://<machine><port>/adminCenterthat is displayed in the server console log, which is automatically displayed in the Console view. If this url isn’t listed, it indicates that the Admin Center hasn’t installed correctly. If this happens, can check the server’s
console.logfor any error relate to Admin Center feature, and check the
server.xmlto make sure there is
- You may get some security exceptions as the URL will redirect to a secure HTTPS URL. Accept any security exceptions and log in using
adminas the user name, and
adminpwdas the password. The Admin Center Toolbox opens.
The Admin Center has now been installed correctly.
Creating a Liberty feature project and an OSGi Web application project
A Liberty feature consists of a feature manifest file and a collection of one or more OSGI bundles so that it can be installed into the Liberty runtime server.
- Create a Liberty Feature Project: File > New > Other …, then select the Liberty Feature Project and click Next.
SampleToolin the Project name field, and choose defaultServer from the Target runtime pull-down, then click Next.
- In the OSGi Bundles Selection Page dialog, click New Bundle… to create the SampleTool Web application bundle (WAB). The WAB is a bundle that contains a web application and that can be deployed in an OSGi container.
SampleToolBundleas the project name. Select the check box for Add Web Support and choose Web 3.0 from the corresponding pull down, then click Next.
- In the Java configuration panel, leave the default settings and click Next.
SampleToolas the context root, then click Next.
SampleToolas the symbolic name for the bundle and leave the version as
1.0.0.qualifier. Click Finish to complete the bundle configuration.
- Ensure that the SampleTool 1.0.0 is selected in the Contained Bundles window. Now click Finish to complete the tool feature configuration.
You have now created a tool feature project.
Configuring the tool feature
This section describes how to configure the feature manifest. A feature is defined by a feature manifest file (
.mf file) that is stored in the
lib/features directory. Installation uses the
OSGI-INF/SUBSYSTEM.MF file from the
ESA file as a new feature manifest that can be copied into the
When editing any manifest the following formatting rules apply:
- If any header is too long for a single line, ensure that any subsequent lines are indented with a single space, otherwise these extra lines will be treated as a new manifest headers, and will cause errors in the manifest.
- A manifest must always end with an empty line.
Editing the tool feature manifest
- Expand the SampleTool project, and in the
OSGI-INFdirectory open the
- On the Overview page, make sure the following values are configured:
Symbolic Name: SampleTool Version: 1.0.0.qualifier IBM-ShortName: SampleTool
- Click the SUBSYSTEM.MF tab at the bottom of the panel to open the Manifest editor.
Add the following headers to the manifest, making sure that each one is on a new line:
Subsystem-Name: %name Subsystem-Description: %description Subsystem-Category: admincenter Subsystem-Localization: OSGI-INF/l10n/subsystem
Add the IBM-Provision-Capability header to the manifest.
IBM-Provision-Capability: osgi.identity; filter:="(&(type=osgi.subsystem.feature) (osgi.identity=com.ibm.websphere.appserver.adminCenter-1.0))"
This header indicates that the tool automatically gets provisioned without the administrator needing to configure it in the
server.xml. The header lists the other features that must be provisioned before this feature can be automatically provisioned. In our case we have a requirement on the Admin Center feature.
Amend the directive on the
Subsytem-Nameto ensure that the feature has protected scope:
Subsystem-SymbolicName: SampleTool; visibility:=protected
- Update the Subsystem-Content header with the value:
Subsystem-Content: SampleTool;version="1.0.0", com.ibm.websphere.appserver.adminCenter-1.0; type="osgi.subsystem.feature"
This header is a comma-separated list of dependent bundles and/or features that this tool feature needs to be available in the runtime. The best practice for Admin Center tools is to also add the Admin Center feature to the
Subsystem-Contentheader. This means that if the feature was ever configured in the
server.xmlit would still define its dependencies.
- (optional) If you wish to add your own icons, you must create icon images. For desktop/tablet icons, the images need to be 142px by 142px, and should be either BMP, JPG or PNG files. If you want the icons to be displayed on phones, the icon size is 78px by 78px. If you do not complete this step the tool will use the Admin Center default tool icons:
- Create a sub-directory called
- Put the icon images in this new
- Add the following header into the Subsystem manifest, substituting the image files names:
Subsystem-Icon: OSGI-INF/icons/<142pxImage>;size=142, OSGI-INF/icons/<78pxImage>;size=78
- Create a sub-directory called
Subsystem-Descriptionin this example are defined to use localization, to allow different translations of the name and description of the tool to be displayed in the Toolbox. In order to define the actual values, we need to configure an localization (l10n) properties file:
- Create a sub directory called
- Create a new file called
subsystem.propertiesin the new
l10ndirectory, and enter the following lines:
name=Sample Test Tool description=A tool that demonstrates how to build Admin Center tools
Subsystem.mfmanifest file should look something like this:
Subsystem-ManifestVersion: 1.0 IBM-Feature-Version: 2 IBM-ShortName: SampleTool Subsystem-SymbolicName: SampleTool;visibility:=protected Subsystem-Version: 1.0.0.qualifier Subsystem-Type: osgi.subsystem.feature Subsystem-Content: SampleTool;version="1.0.0", com.ibm.websphere.appserver.adminCenter-1.0; type="osgi.subsystem.feature" Manifest-Version: 1.0 Subsystem-Name: %name Subsystem-Description: %description Subsystem-Category: admincenter Subsystem-Localization: OSGI-INF/l10n/subsystem IBM-Provision-Capability: osgi.identity; filter:="(&;(type=osgi.subsystem.feature) (osgi.identity=com.ibm.websphere.appserver.adminCenter-1.0))" Subsystem-Icon: OSGI-INF/icons/toolicon-142.png;size=142,OSGI-INF/icons/toolicon-78.png;size=78 < empty line here >
- Create a sub directory called
Updating the Tool Bundle
We have defined the tool feature which describes how to display the tool in the Admin Center’s Toolbox, but we need to write a bundle that will actually do something when we run the tool.
The Admin Center reads the
Subsystem-Content header of the feature, to identify all of the Web bundles that the feature contains. It then reads the manifests of these bundles to identify which one should be called from the Toolbox of the Admin Center. It uses the following rules:
- If any of the bundles contains an
IBM-AdminCenter-PrimaryEndpointmanifest header whose value is this tool’s feature
symbolicName, then this bundle’s context root will be invoked when the tool is run.
- If multiple bundles contain the header for this feature, then the 1st bundle that is read that has this header will be used.
- If no header, or no matching header is found, and the feature only contains 1 web bundle, that will be used by default.
- If multiple web bundles are specified, but none contain either the
primaryEndpointheader for this feature, or
primaryEndpointmanifest header at all, then the context root of the first bundle processed is used.
It is best practice to always define the
IBM-AdminCenter-PrimaryEndpoint header in the bundle that should be initially invoked, even if you only have a single web bundle in the tool. Without this header, if a tool is ever updated in the future, the alteration could potentially affect the order that the web bundles get processed, and therefore alter the behaviour of the tool.
The format of the header is:
IBM-AdminCenter-PrimaryEndpoint: <Liberty feature project’s symbolic name>
- Expand the SampleToolBundle project, then expand WebContent > META-INF.
- Open the
MANIFEST.MFfile in the manifest editor.
- Click the MANIFEST.MF tab to show the XML version of the manifest.
- Add the following line to the manifest:
Manifest.mffile should now look something like this:
Manifest-Version: 1.0 Bundle-ManifestVersion: 2 Bundle-Name: SampleToolBundle Bundle-SymbolicName: SampleTool Bundle-Version: 1.0.0.qualifier Bundle-ClassPath: WEB-INF/classes Bundle-RequiredExecutionEnvironment: JavaSE-1.6 Web-ContextPath: /SampleTool Import-Package: javax.el;version="2.0", javax.servlet;version="2.5", javax.servlet.annotation, javax.servlet.http;version="2.5", javax.servlet.jsp;version="2.0", javax.servlet.jsp.el;version="2.0", javax.servlet.jsp.tagext;version="2.0" IBM-AdminCenter-PrimaryEndpoint: SampleTool < empty line here >
Create the HTML page for the tool
The Admin Center invokes the default JSP/HTML file that is defined at the context root of the bundle; e.g
index.html or other files defined in the
welcome-list element of the
- Right-click the WebContent directory of the SampleToolBundle project, then click New > File.
- Name the file
index.htmland click Finish.
- In the Source tab of the index.html panel, create some HTML that will display a message when the tool is run:
<html> <body> <h1>We're running SampleTool ! </h1> </body> </html>
- Save this file.
Installing the tool into the Liberty runtime
- Ensure that the server is started.
- Open the Java EE perspective.
- In the Enterprise Explorer, right-click the SampleTool project and click Install Feature.
- In the dialog, ensure the
defaultServeris selected, and click Finish.
- You will be prompted to restart the server but you don’t need to do this as the Admin Center tools can be installed into a running Liberty Server. So click Cancel.
- The tool is now available to use in the Admin Center. Sign into the Admin Center.
- From the Toolbox screen, click the Edit button
in the top left hand corner of the Toolbox.
- Now click the Add Tool button
that should now be in the top-left-hand corner.
- Select the Add Tool option from the resulting drop down panel.
- You should now see the new tool listed with the existing tools, but the new tool should have a
icon associated with it. Click this icon, then click Add from the Add Tool dialog and the tool will now have an icon, meaning that the tool will be listed in the users Toolbox.
- Click the Toolbox icon
to go back to the Toolbox.
- You should now see the new tool, with the specified supplied icon, or a default icon if no icons were defined in the feature manifest.
- Click the new tool icon to run the tool. This should take you to a new page in the browser with the message:
We’re running SampleTool !
Where do I go from here?
Hopefully you’ll need a tool that does more than print a message. You can add as many tools as you want, but if you want to develop the existing tool you will need to remove the old version and install the new version of the ESA each time.
To reinstall the tool you will need to:
- Remove the tool from the Toolbox.
- If you are not currently in the Toolbox, click the Home button
to get back to the Toolbox.
- Click the Edit button
which is in the top left hand corner of the Toolbox.
- All the tools in the Toolbox should be listed with a remove icon
. Click this then click Remove from the following pop-up dialog box.
- Click the complete action button
in the top right hand corner.
- If you are not currently in the Toolbox, click the Home button
- Go back to the Java EE perspective, right-click the SampleTool project, then click Update Feature. Follow the instructions on the screen. It will require a restart of the server.
- You can then re-add the tool to the Admin Center Toolbox.
Exporting the tool to run in a different Liberty runtime
If you need to install the tool into a standalone Liberty runtime, you will need to export it as an ESA (Enterprise Subsystem Archive).
- Right-click the SampleTool project, then click Export > Liberty Feature (ESA).
- In the To ESA File field, enter the destination path name for the new ESA.
- Ensure that SampleTool (1.0.0.qualifier) is checked in the Bundles to include list, then click Finish.
- Use the
featureManagercommand line tool to install the exported ESA into the Liberty runtime:
featureManager install <path to exported SampleTool ESA>
./featureManager install <path to exported SampleTool ESA>