Introduction

In this article, you'll learn how to create custom widgets with IBM Integration Designer for use in Business Space. You'll learn how to catalog widgets, as well as how to deploy and test them in an iterative development fashion.

You'll create two widgets. One widget is a Hello World example that uses static HTML. The second widget requires JavaScript to build dynamic HTML to access REST services to display records in a grid. By supplying different REST URI's, you can access information for BPEL processes, process applications and monitor models.

A Business Space widget uses a number of different files. Business Space defines its widgets using XML files that conform to the iWidget 2.1 specification.

• The iWidget XML file describes the properties of the widget. The properties include the name and description of the widget, its attributes, and the events that it might produce or accept.
• The catalog file registers the widget in Business Space and identifies the category to which the widget belongs.
• The JavaScript file defines the custom behavior of the widget.

Prerequisites

In order to complete the steps in this article, you'll need the following software:

• IBM Integration Designer V7.5. Ensure that the Web development tools feature is installed in IBM Integration Designer. If not, launch the installer again to add this feature. If this feature is not installed, you won't be able to use the iWidget wizard and the Universal Test Client for iWidgets.

  To verify that the Web development tools feature is installed, from IBM Integration Designer, select Window => Open Perspective. You should see the Web perspective listed.

• IBM Business Process Manager V7.5 Advanced Edition server, or IBM Business Monitor V7.5 server or IBM Business Process Manager V7.5 server augmented with IBM Business Monitor. The server can be the toolkit server or a separate server.
• The sample file CustomWidgetWithREST.zip supplied with this article (downloaded and unzipped).

Back to top

Create the Hello World widget

This section shows you how to create the Hello World widget, which displays static HTML. You'll create the project, test the widget, catalog the widget, and create a dashboard to display the widget.

Create a new dynamic web project

Create a new dynamic web project called myWidgets by doing the following:

1. Start IBM Integration Designer and, when prompted, point to a new workspace such as c:\workspaces\widget.
2. Close the Welcome tab.
3. Open the Web perspective by selecting Window => Open Perspective => Web.
4. Right-click the Enterprise Explorer, then select New +> Project.
5. Select Web => Dynamic web project and click Next.
6. For the project name, specify myWidgets.
7. Click Finish.

   You'll see two new projects in the Enterprise Explorer view, myWidgets and myWidgetsEar.

Create the helloWorld XML file

Create the widget XML file helloWorld.xml in the WebContent folder as follows:

1. In the Enterprise Explorer view, select myWidgets => WebContent.
2. Right-click the Enterprise Explorer, then select New => Other.
3. Select Web => iWidget and click Next.
4. For the iWidget name, specify helloWorld.
5. The iWidget type defaults to Simple Widget.
6. Click Finish.
7. The xml file opens so that you can add the HTML content. Add a paragraph with some text using either the Design tab or the Source tab.
   • On the Design tab, you can add the element in the details for the Content section, as shown in Figure 1.
     
     Figure 1. iWidget editor Design tab
     
     
     
   • On the Source tab, you add the element in the CDATA section, as shown in Figure 2.
     
     Figure 2. iWidget editor Source tab
     
     
     
8. Press Ctrl-S to save your work.

Test the widget

Test the widget using the built-in J2EE preview server as follows:

1. Open the Servers view, then right-click in the view and select New => Server.
2. In the New Server wizard, select the Basic server type and J2EE Preview server, then click Finish.
3. In the Servers view, select J2EE Preview server, then right-click and select Add and Remove.
4. Add the myWidgets project and click Finish.
5. Right-click on the server instance that you created to start it, as shown in Figure 3.
   
   Figure 3. myWidgets on the server
   
   
   
6. In the Enterprise Explorer view, navigate to WebContent, then right-click helloWorld.xml and select Run As => Run on Server.
7. In the Run on Server wizard, select the server where you deployed the sample and click Finish.

   The widget opens in the Universal Test Client for iWidgets. Here you can test your widgets, send events to the widget, view events sent and view events received. The Hello World widget doesn't process events so it's sufficient to see that it displays your HTML correctly.

   
   
   Figure 4. Universal Test Client for iWidgets
   
   
   

Deploy the widget to Business Space

After testing the widget in the test client, deploy the widget to Business Space. In Business Space, a widget palette provides a list of widgets available for your use. The palette has categories that group widgets based on usage. For example, there are categories for Business Monitoring and Human Task Management. XML files are used to provide this information.

1. Create a folder called iWidget/images for the widget image and place the widget image in the folder as follows:
   1. In the Enterprise Explorer view, select myWidgets => WebContent.
   2. Right-click the Enterprise Explorer, then select New => Other.
   3. Select General => Folder, then click Next.
   4. For the folder name, specify images and click Finish.
   5. You can use the generic widget gif for this example. You can find generic_iWidget.gif in C:\<profile-path>\installedApps\<cell-name>\BspaceEAR_<node_server>.ear\BSpace.war\iWidget\images. Copy this file by dragging it to the iWidget/images folder that you just created, as shown in Figure 5.
      
      Figure 5. Widget image file
      
      
      
2. Deploy the EAR to the server that is running Business Space as follows:
   1. Check the Problems tab for any errors and resolve these before continuing.
   2. Click the Servers tab, then right-click and select Start to start the server. This may take a few minutes to complete.
   3. Right-click in the Servers view, then select Add and Remove Projects.
   4. Click Add to move myWidgetsEar from the list of available projects to the list of configured projects, then click Finish. myWidgetsEAR is now added to the server, as shown in Figure 6.
      
      Figure 6. myWidgetsEAR added to the server
      
      
      
3. Load the supplied catalog file to the project as follows:
   1. Create a new folder called catalog in the myWidgets project.
   2. Drag the supplied catalog file catalog_myWidgets.xml from the file system explorer to the new catalog folder in myWidgets project. Note that the file name must be in the format: catalog_<name>.xml
4. Review the tags in the catalog file:
   1. The category tag identifies the new category My Widgets in the palette.
   2. The first entry tag defines the new widget myhello with title Hello World, which the definition tag shows to be located at /myWidgets/helloWorld.xml. There are also several tags to specify the images to be associated with the widget.
   3. The second entry tag defines the second widget that you will use later in this article.
5. Export the catalog file to a zip file, as shown in Figure 7:
   1. Select the catalog folder in myProjects.
   2. Select File => Export => Java => JAR.
   3. Select Export Java source files and resources.
   4. Select an export destination.
   5. Select Add directory entries.
      
      Figure 7. Export the catalog file
      
      
      
   6. Click Finish.
6. Run the script to load the catalog file to the Business Space server as follows:
   1. Create a Jython project InstallWidget to contain the script.
   2. Drag the supplied script file myWidgets_install.py from the file system explorer to the InstallWidget project.
   3. Open the file and update the parameters nodeName and serverName for your installation configuration. Also, specify the path to the catalog zip file that you created earlier. This is an example of the command to run:

      AdminTask.installBusinessSpaceWidgets('[-nodeName yourNode -serverName server1 -widgets c:/temp/myWidgetsCatalog.zip]')

      
      

      Later, if you want to update or delete the widget catalog, you can run commands updateBusinessSpaceWidgets or uninstallBusinessSpaceWidgets with the same parameters.

   4. Right-click on the script file in the project then select Run As => Administrative script.
   5. As shown in Figure 8, select the runtime environment server and the profile name. For wsadmin arguments enter –conntype NONE, then enter the security information.
      
      Figure 8. Run the install script
      
      
      
   6. Click Run.
   7. Check the Console view and you should see a message with the trace file name; for example:

      CWMO1111I: Information is being logged to the c:\bpm751\profiles\ProcCtr01\logs\installBusinessSpaceWidgets. May-08-12.23.40-GMT-06.00-2012.trace file.

      
      

      If you open this trace file and you should see a message at the end similar to:

      i) [5/8/12 12:23:44 PM GMT-06:00] 1 BSpaceInstallWi F execute Completed installing Business Space widgets...

      
      
   8. Anytime you run the script installBusinessSpaceWidgets, do the following to see the updates in Business Space:
      1. Restart the server.
      2. Clear the cache in the browser.

         In Firefox, depending on the version, select Tools => Clear recent history => Select cookies & cache => Clear now or History => Clear recent history.

         In Internet Explorer, depending on the version, select Tools => Delete browsing history or Tools => Internet options => Browsing history.

Create a dashboard and add the widget

Create a dashboard and add the new Hello World widget as follows:

1. Launch Business Space in your browser (for example, https://localhost:9444/BusinessSpace).
2. When prompted, enter the user and password.
3. Select Manage Spaces => Create Space.
4. Specify a name such as Dashboard, then click Save.
5. Specify a page name, then click OK.
6. In the list of spaces, select the newly created space to open it.
7. Click Edit Page. If no widgets show up in the widget palette and you see the message "No results," try logging out of Business Space, clearing the cache and logging back in. You may have to repeat this a few times.
8. Look for the new category My Widgets (2) in the drop-down, and select it, as shown in Figure 9.
   
   Figure 9. New category for your widgets
   
   
   
9. You should see the two new widgets listed, as shown in Figure 10.
   
   Figure 10. Your widgets in the Business Space palette
   
   
   
10. If your widgets are not listed, there may be an error in your widget xml file. Check the Server Logs view in Integration Designer, and look for a message indicating an error loading the catalog. For example, the message below shows that there is a missing end tag:

    com.ibm.mm.server.model.catalog.persist.CatalogModelPersistenceHandlerImpl loadChildren ERROR_LOADING_CATEGORIES_1 com.ibm.mm.framework.persistence.exceptions.DataBackendException: PROBLEM_LOADING_CATALOG_1 at … Caused by: org.xml.sax.SAXParseException: The element type "preview" must be terminated by the matching end-tag "</preview>".

    
    
11. Drag the Hello World widget to the page or select the + to add it to the page. The widget displays the text that you entered when defining the widget.
12. You should see the two new widgets listed, as shown in Figure 11.
    
    Figure 11. Hello World widget on the page
    
    
    

Back to top

Create a widget to access REST services

In this section, you'll create a widget that demonstrates dynamic content. It uses a JavaScript file to access REST services to retrieve business process or monitor model information, and it displays that in the widget within a grid.

When developing widgets, you can make changes to the widget's JavaScript and xml files in the project. To see the updates, publish the project to the server, then clear cache in the browser and reload the Business Space page.

For debugging your widget, you can use debug statements in your widget JavaScript, then you can use Firebug to view these debug output strings in the client. For example: console.debug("debug text..."). A printDebug statement is also provided by the iWidget infrastructure. The output of this to the client is controlled by the server trace setting (com.ibm.bspace.manager = fine or above). For example: this.printDebug("debug text…").

1. Rather than creating the widget from scratch, copy the supplied listGrid.js and listGrid.xml files to the myWidgets project by dragging the files from the file system explorer to myWidgets\WebContent in IBM Integration Designer, as shown in Figure 12.
   
   Figure 12. Copy the supplied widget files to your project
   
   
   
2. Double-click on the file listGrid.xml to open the editor. Then click the Source tab at the bottom of the editor.

   The itemSet tag contains the following item: <iw:item id="allowedModels" value=".*"/>, which is used by the widget to specify a regular expression pattern for matching to the records that are retrieved from REST. The default expression is .* so all records are retrieved. However, you can change this expression to filter the matches.

   The resource tag <iw:resource src="listGrid.js" /> refers to the JavaScript file for the widget, listGrid.js.

   The CDATA tag contains the HTML that will be displayed in the widget. The JavaScript will construct the dynamic content and then set the values of these elements. Note that the elements use _IWID_ in the naming convention of the HTML elements. When there are multiple copies of a widget on a page, a unique name is necessary, so the iWidget infrastructure automatically substitutes a unique identifier for the _IWID_ string in the element name. For example, the XML file contains a span element with the ID _IWID_bspace_filterPattern, so listGrid.js contains a line that constructs the true name of the element in this manner:

   var nodeId = "_" + this.iContext.widgetId + "_" +"bspace_filterPattern";

   
   
3. Double-click on listGrid.js to open it in the editor.

   Near the top of the file, notice the statements that declare the REST URIs. Following each REST URI is the column definition for the grid. There are three sets of these, for the monitor models, process templates and process applications. Figure 13 shows the monitor model section.

   
   
   Figure 13. The REST URI and columns to display in the grid
   
   
   

   The URIs that are used by the program are as follows:

   • Monitor models: /rest/bpm/monitor/models
   • Process templates: /rest/bpm/bfm/v1/processTemplates/filter
   • Process applications: /rest/bpm/wle/v1/processApps

   The following standard functions are required to handle widget events: onLoad, onReload, onview, onUnload. Notice also the cleanElements function, which is called by onUnload. It's a good idea to destroy any HTML elements that you have created to avoid memory leaks.

   The findRecords function, shown in Figure 14, accesses the specified REST URI to retrieve the information, using the Dojo toolkit command xhrGet. For more information, see the Dojo toolkit documentation.

   
   
   Figure 14. Function to access the REST URI
   
   
   
4. Update the program to display either process applications, process templates or monitor models, as shown in Figure 15. The program accesses only one REST URI at a time. To change which REST URI is accessed, update the onview function. Uncomment two lines for the appropriate REST URI. In this example the REST URI and columns are being set to display process applications.
   
   Figure 15. Select the URI and columns to display in the widget
   
   
   

   Press Ctrl-S to save your changes.

5. Check the Problems tab for any errors and resolve these before continuing.
6. Click the Servers tab, then right-click and select Publish to publish your changes to the server.
7. Log out of Business Space, clear the browser cache, then log in to Business Space again.
8. Add the widget to your dashboard as follows:
   1. Click Edit Page and select My Widgets (2) in the drop-down. You should see the two widgets listed, as shown in Figure 16.
      
      Figure 16. Your widgets on the Business Space palette
      
      
      
   2. Drag the widget List REST resources in a grid to the page or select + to add it to the page.
   3. The widget should show records in the grid for the REST URI that you selected in the program. For example, Figure 17 shows a list of process applications.
      
      Figure 17. Your widget showing process applications
      
      
      

Back to top

Conclusion

In this article you created a simple Hello World widget to display static HTML in Business Space. You learned how to create, test, deploy and catalog the widget. You also reviewed a custom widget and learned how to access REST api's to display lists of data in a grid.

Back to top

Download

Information about download methods

Resources

• REST (Representational State Transfer) APIs
  
  
• Using the REST APIs in IBM Business Process Manager V7.5
  
  
• Developing for Business Space (Business Space Information Center)
  
  
• Building IBM Business Process Management Solutions Using WebSphere V7 and Business Space: Refer to "Part 3: Developing clients and custom widgets" for information on how to create a REST service and a custom widget to invoke the service.
  
  
• Developing custom widgets for Business Space using Dojo series
  
  
• IBM Education Assistant, Business Process Management
  
  
• IBM Business Process Manager Information Center
  
  
• developerWorks BPM zone: Get the latest technical resources on IBM BPM solutions, including downloads, demos, articles, tutorials, events, webcasts, and more.
  
  
• IBM BPM Journal: Get the latest articles and columns on BPM solutions in this quarterly journal, also available in both Kindle and PDF versions.
  
  

About the author

Scott Walden has been with IBM since 1981, working in Global Services and Software Group. He is currently a software engineer in Software Group in Application Integration Middleware Early Programs and is on the technical team supporting beta programs for IBM Business Process Management products. He has worked on many beta and early programs since 2003, and has extensive experience with the IBM BPM products.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Create the Hello World widget
• Create a widget to access REST services
• Conclusion
• Download
• Resources
• About the author
• Comments

Next steps from IBM

• Try: IBM Business Process Manager
• Demo: IBM Business Process Manager demos
• Buy: IBM Business Process Manager

Dig deeper into Business process management on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers