How to build your own tool for the WAS Liberty Admin Center.

Before you begin:

  • Download and install WAS Liberty (WAS Liberty V8.5.5.4 Runtime or later; or the latest Beta Runtime) with the WebSphere Developer Tools (WDT) for Eclipse.
  • Create a server called defaultServer.

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 featureManager script.

To install the Admin Center feature from WDT:

  1. 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….
  2. In the filter box of the Liberty Add-ons dialog, type Admin Center to display the Admin Center feature in the window.
  3. Click the Install button for the Admin Center feature and the button label changes to Install Pending.
  4. 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:

  1. Change to your Liberty installation location; e.g. C:wlpbin.
  2. 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.

  1. In the Servers view of Eclipse, expand the server and double-click the Server Configuration [server.xml] element.
  2. 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.2 feature is enabled on the server.
  3. 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.
  4. Now click the Server Configuration element in the Configuration Structure pane and click Add….
  5. 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.
  6. Enter admin into the User name field, and adminpwd into the Password field.
  7. Now click the Server Configuration element again and add the Keystore element.
  8. In the editor, click the Keystore element, then enter liberty in the Password field in the right-hand side of the panel. Leave all other field values as they are.
  9. Save this configuration change and close the editor.
  10. Start the server: in the Servers view, right-click defaultServer > Start.
  11. To access the Admin Center, click the URL http://<machine><port>/adminCenter that 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.log for any error relate to Admin Center feature, and check the server.xml to make sure there is <feature>adminCenter-1.0</feature> entry.

  12. You may get some security exceptions as the URL will redirect to a secure HTTPS URL. Accept any security exceptions and log in using admin as the user name, and adminpwd as 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.

  1. Create a Liberty Feature Project: File > New > Other …, then select the Liberty Feature Project and click Next.
  2. Enter SampleTool in the Project name field, and choose defaultServer from the Target runtime pull-down, then click Next.
  3. 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.
  4. Enter SampleToolBundle as the project name. Select the check box for Add Web Support and choose Web 3.0 from the corresponding pull down, then click Next.
  5. In the Java configuration panel, leave the default settings and click Next.
  6. Enter SampleTool as the context root, then click Next.
  7. Enter SampleTool as the symbolic name for the bundle and leave the version as 1.0.0.qualifier. Click Finish to complete the bundle configuration.
  8. 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 ${wlp.user.dir}/lib/features directory.

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

  1. Expand the SampleTool project, and in the OSGI-INF directory open the SUBSYSTEM.MF file.
  2. On the Overview page, make sure the following values are configured:
            Symbolic Name: SampleTool
            Version: 1.0.0.qualifier
            IBM-ShortName: SampleTool
      
  3. Click the SUBSYSTEM.MF tab at the bottom of the panel to open the Manifest editor.
  4. 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
      
  5. 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.

  6. Amend the directive on the Subsytem-Name to ensure that the feature has protected scope:

            Subsystem-SymbolicName: SampleTool; visibility:=protected
      
  7. 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-Content header. This means that if the feature was ever configured in the server.xml it would still define its dependencies.

  8. (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:
    1. Create a sub-directory called icons in the OSGI-INF directory.
    2. Put the icon images in this new icons directory.
    3. 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
          
  9. The Subsystem-Name and Subsystem-Description in 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:

    1. Create a sub directory called l10n in the OSGI-INF directory.
    2. Create a new file called subsystem.properties in the new l10n directory, and enter the following lines:
      name=Sample Test Tool
      description=A tool that demonstrates how to build Admin Center tools
            

    The Subsystem.mf manifest 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 >
          

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-PrimaryEndpoint manifest 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 primaryEndpoint header for this feature, or primaryEndpoint manifest 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>

  1. Expand the SampleToolBundle project, then expand WebContent > META-INF.
  2. Open the MANIFEST.MF file in the manifest editor.
  3. Click the MANIFEST.MF tab to show the XML version of the manifest.
  4. Add the following line to the manifest:
    IBM-AdminCenter-PrimaryEndpoint: SampleTool
      

    The Manifest.mf file 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.jsp, index.html or other files defined in the welcome-list element of the web.xml.

  1. Right-click the WebContent directory of the SampleToolBundle project, then click New > File.
  2. Name the file index.html and click Finish.
  3. 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>
      
  4. Save this file.

Installing the tool into the Liberty runtime

  1. Ensure that the server is started.
  2. Open the Java EE perspective.
  3. In the Enterprise Explorer, right-click the SampleTool project and click Install Feature.
  4. In the dialog, ensure the defaultServer is selected, and click Finish.
  5. 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.
  6. The tool is now available to use in the Admin Center. Sign into the Admin Center.
  7. From the Toolbox screen, click the Edit button
    Edit Button in the top left hand corner of the Toolbox.
  8. Now click the Add Tool button
    Add Button that should now be in the top-left-hand corner.
  9. Select the Add Tool option from the resulting drop down panel.
  10. 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.
  11. Click the Toolbox icon
    Home Button to go back to the Toolbox.
  12. 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.
  13. 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:

  1. Remove the tool from the Toolbox.
    1. If you are not currently in the Toolbox, click the Home button
      to get back to the Toolbox.
    2. Click the Edit button
      Edit Button which is in the top left hand corner of the Toolbox.
    3. 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.
    4. Click the complete action button
      Done Button in the top right hand corner.
  2. 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.
  3. 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).

  1. Right-click the SampleTool project, then click Export > Liberty Feature (ESA).
  2. In the To ESA File field, enter the destination path name for the new ESA.
  3. Ensure that SampleTool (1.0.0.qualifier) is checked in the Bundles to include list, then click Finish.
  4. Use the featureManager command line tool to install the exported ESA into the Liberty runtime:

    On Windows: featureManager install <path to exported SampleTool ESA>

    On Linux: ./featureManager install <path to exported SampleTool ESA>

Join The Discussion

Your email address will not be published. Required fields are marked *