Mohammed Atef’s Technical blog

Build and register a IBM Case Manager custom Widget


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=""
   3: xmlns:iw=""
   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://</definition>
   8: <preview>
   9: endpoint://
  10: </preview>
  11: <icon>endpoint://</icon>
  12: <previewThumbnail>endpoint://</previewThumbnail>            <help>endpoint://{}bspaceWidgetHelpRootId/topic/</help>
  13: <shortDescription> <nls-string lang="en">HelloWorld</nls-string></shortDescription>        <metadata name=""></metadata>            <metadata name="">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 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="" xmlns:xsi="" xsi:schemaLocation=" BusinessSpaceRegistry.xsd ">    <tns:Endpoint>    <tns:id></tns:id>    <tns:type></tns:type>
   3:     <tns:version></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]’)
  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]’)
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\}

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.


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 .


May 31, 2013 - Posted by | Developement, ECM, FileNet, IBM Case Manager, XML,XSL,XSLT,DHTML,HML,CSS | , , , , , , , , , , , , ,


  1. […] (web.xml, CustomSearch.js, CustomSearch.xml) , for more information about this files visit this link […]

    Pingback by IBM Case Manager Custom search Widget « Mohammed Atef’s Technical blog | May 31, 2013 | Reply

  2. Hi,

    Thanks for this…

    Comment by cliepkept | June 9, 2013 | Reply

  3. hi

    Comment by layeltlierly | August 8, 2013 | Reply

    • hi any help

      Comment by mohammedatef83 | August 26, 2013 | Reply

  4. Hi.
    Thank you for this introduction.
    I always get an syntax error if i use the language jython (I’m sure that the syntax is right). I tried the other language ‘Jacl’ with the specific syntax:
    wsadmin>$AdminTask installBusinessSpaceWidgets{-serverName server1 -nodeName Node11 -widgets C:\}
    Then i get the error:
    no accessible method “installBusinessSpaceWidgets{-serverName” in class while …
    I found the command ‘print“installBusinessSpaceWidgets”)’ but this also does not work.

    I think that there is a missing component. Can someone help?

    Comment by matthew | January 14, 2014 | Reply

    • Hi, actually I tried the second deployment method of time, but first one I did it many times and works fine. Try the first deployment option and let me know.


      Comment by mohammedatef83 | January 14, 2014 | Reply

      • Hi. Thank you for your quick response.
        I tried the first deployment option and get the same exception at “updateBusinessSpaceWidgets” – no accessible method by using Jacl and “AttributeError: updateBusinessSpaceWidgets” with jython.
        command: AdminTask.updateBusinessSpaceWidgets(‘[-nodeName xyz -serverName server1 -catalogs C:\catalog_HelloWorld.xml]‘)

        It seems to me that no command works.

        Comment by matthew | January 15, 2014

    • Hi matthew,

      Did you using case manager 5.1.1 I used same script in different environments and works fine

      Comment by mohammedatef83 | January 15, 2014 | Reply

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: