Build and register a IBM Case Manager custom Widget

Introduction

As a user interface developer for IBM Case Manager, you need to customize Case Manager Client by creating your custom Widgets. Here I am going to share with you basics for developing, deploying and registering Custom Widgets.
Our use case for this post is creating custom widget to print hello world message.

Application structure

we know that each application should have known structure, Below table shows the application files structure.

File or folder name	Description
HelloWorld	Web project name and folder
HelloWorld.xml	Widget definition file
Web.xml	Configuration file

Create a web project

First, we have to create new project using Eclipse, so please follow this procedures to create a new web project

1- Open Eclipse, Click File > New > Dynamic web project

2- Follow the wizard to create project, but do not forget to set project name HelloWorld and to tick Generate web.xml deployment descriptor check box.

3- Open Project Explorer pane, expand the HelloWorld node and expand the WebContent > WEB-INF folder, then Open the web.

4- Add the following entry to include the BasicWidget.xml to the welcome file:
<welcome-file> HelloWorld.xml</welcome-file>       , then save the file.
5- Add new file with the following names HelloWorld.xml

Modify Widget Definition file

• Open the HellowWrold.xml file and add the following lines of codes, then save the file.

   1: <?xml version="1.0" encoding="UTF-8" ?>

   2: <iw:iwidget id="HelloWorld" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

   3: xmlns:iw="http://www.ibm.com/xmlns/prod/iWidget"

   4: supportedModes="view edit" iScope=" HelloWorldScope">

   5: <iw:content mode="view">

   6: <![CDATA[ <h1>Hello World</h1> ]]>

   7: </iw:content>

   8: </iw:iwidget>

• Above code is very clear but we need to highlight some attributes here
• supportedModes: this attribute used to determine if users can view or edit the widget.
• iScope: The iScope is a Dojo wrapper class for the Custom widget
• iw:content: it is content area for the edit or view mode in your Widget.

Create Catalog file

• Create new xml file name it catalog_HelloWorld.xml and add the following list of code to it then save.
  

   1: <?xml version="1.0" encoding="UTF-8"?>

   2: <catalog id="Demo"> <resource-type>Catalog</resource-type>

   3: <category name="Demo">

   4:     <title> <nls-string lang="en">HelloWorld</nls-string></title>

   5:     <description> <nls-string lang="en">HelloWorld</nls-string>    </description>    

   6:     <entry id="iWidget.widgets.HelloWorld" unique-name="iWidget.widgets.HelloWorld">                <title> <nls-string lang="en">HelloWorld</nls-string> </title>

   7:         <description> <nls-string lang="en">HelloWorld</nls-string> </description>                <definition>endpoint://com.ibm.im.HelloWorldRootId/HelloWorld.xml</definition>

   8: <preview>

   9: endpoint://com.ibm.im.HelloWorldRootId/HelloWorld/image/thumbnails/viewer_preview.gif

  10: </preview>

  11: <icon>endpoint://com.ibm.im.HelloWorldRootId/HelloWorld/image/viewer_18.gif</icon>

  12: <previewThumbnail>endpoint://com.ibm.im.HelloWorldRootId/HelloWorld/image/thumbnails/viewer_thumb.gif</previewThumbnail>            <help>endpoint://{com.ibm.bspace}bspaceWidgetHelpRootId/topic/com.ibm.p8.widgetsref.doc/viewer_widget.htm</help>

  13: <shortDescription> <nls-string lang="en">HelloWorld</nls-string></shortDescription>        <metadata name="com.ibm.bspace.version">1.0.0.0</metadata>            <metadata name="com.ibm.bspace.owner">International Business Machines Corp.</metadata>

  14: </entry></category></catalog>

• now let’s talk a look at this file
• entry ID: is the widget id for the business space and it should be unique
• category name: used to add this widget to an exist category or and new category for the new widget if not exist.
• Other attributes used for determine widget title, description, icons, images.

Create End point file

• It is the last file, we need to build end point file, actually it is very short.so please create new xml file and name it HelloWorldEndPoint.xml and add the following lines of code there.

   1: <?xml version="1.0" encoding="UTF-8"?>

   2: <tns:BusinessSpaceRegistry xmlns:tns="http://com.ibm.bspace/BusinessSpaceRegistry" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://com.ibm.bspace/BusinessSpaceRegistry BusinessSpaceRegistry.xsd ">    <tns:Endpoint>    <tns:id>com.ibm.im.HelloWorldRootId</tns:id>    <tns:type>com.ibm.im.HelloWorldRootId</tns:type>

   3:     <tns:version>1.0.0.0</tns:version>

   4:     <tns:url>/HelloWorld/</tns:url>

   5:     <tns:description>Location of Hello World</tns:description>

   6:   </tns:Endpoint>    </tns:BusinessSpaceRegistry>

Deploy and register the Widget

We have finished all development effort and we are going forward to deploy and register the new widget to case manager client.

However, we have can follow two options to do this, I will share with both of them now

• First option: export project as war and register the catalog and endpoint xml files
• Second option: export project as ear and zip it with the catalog and endpoint xml files

Export project as war and register the catalog and endpoint files

Here we are going to export the HelloWorld project as war file, let’s see procedures to do this

1. Click File > export > war file
2. select war file path for exporting and then finish
3. Go to websphere and deploy the war file and keep the web application name HelloWorld
4. Register the catalog file by following the below steps
1. Open windows command and go to the web sphere bin folder
2. Run the below commands
1. wsadmin -user user1 -password pwd1 -lang jython
2. AdminTask.updateBusinessSpaceWidgets(‘[-nodeName node1 -serverName server1
   
   -catalogs C:\HellowWolrd\catalog_ HellowWolrd.xml]’)
3. AdminConfig.save()
5. Register the End point file by following the below steps
1. Open windows command and go to the web sphere bin folder
2. Run the below commands
1. wsadmin -user user1 -password pwd1 -lang jython
2. AdminTask.updateBusinessSpaceWidgets(‘[-nodeName node1 -serverName server1 –endpoints C:\HellowWolrd\HellowWolrdEndPoint.xml]’)
3. AdminConfig.save()

Export project as ear and zip it with catalog and endpoint files

Here we are going to export our project as ear file and without deploying it to Websphere, we will create one package and with couple of command lines we will deploy and register our widget.

Let’s see how it goes here:

1. 1- Open Eclipse and create new Enterprise application project
2. 2- Select HelloWorld from Java EE module dependencies, then click finish
3. 3- Click File > Export EAR , set the ear file name helloworld
4. 4- Create folder named HelloWorld and copy the following files to it (HelloWorld.ear, catalog_HelloWorld.xml, HelloWorldEndpoints.xml)
5. Zip the HelloWorld folder
6. Open windows command and go to the web sphere bin folder
7. Run the following commands
1. wsadmin -user user1 -password pwd1 -lang jython
2. AdminTask installBusinessSpaceWidgets {-serverName server1 -nodeName node1 -widgets C:\HellowWolrd\ HellowWolrd.zip}

Testing Widget

Eventually, we have finished developing, deploying and registering the Hello World widget now you can open any page in your case client and click Edit page link then drag the hello world widget there.

Conclusion

In this post I tried to share with you how to build and deploy IBM case manager widget and also to register it in two different ways, hope that helped.

Now you can download all resources related to this post from here .