Build FileNet BPM applications using IBM ECM Widgets, Part 3: Expanding ECM Widgets using third-party widgets

With IBM Enterprise Content Management Widgets (ECM Widgets), business analysts can easily design and create new enterprise applications to meet business requirements. The ECM Widgets application provides rich user interfaces to communicate with third-party widgets. Business analysts can create their own widgets or use existing widgets to connect with ECM Widgets to gain more business value. This article, the third and last in the series, shows you the IBM iWidget event mechanism, the ECM Widgets event framework, and how to develop an application that combines third-party widgets and ECM Widgets.


Xin Yu Zhou (, Software Engineer, IBM

Photo of Xin ZhouXin Yu Zhou is a software engineer in IBM China Software Development Lab (CSDL). He works on IBM FileNet products development in IBM Information Management.

Shao Hong Xu (, Software Engineer, IBM

Photo of Shao Hung XuShao Hong Xu is a software engineer in IBM China Software Development Lab (CSDL). He has rich experience in designing IBM FileNet solutions, in developing Javascript based on Dojo, and in tuning Web client performance.

19 November 2009


IBM Enterprise Content Management Widgets (ECM Widgets) is a new Web 2.0 application based on mashup technology. ECM Widgets is an important component of the IBM Agile ECM FileNet® portfolio. It provides a set of widgets for business designers, analysts, IT specialists, and end users. The ECM Widgets application is highly flexible, easy to use, and convenient to expand. A user can quickly construct a FileNet business process management (BPM) solution by dragging and dropping widgets to easily configure the solution. ECM Widgets can significantly reduce the cost of implementation for enterprise business process management.

ECM widgets comply with the IBM iWidget Specification Version 1.0, and the widgets run on an IBM mashup platform. Specifically, the ECM Widgets 4.5.1 runs on IBM WebSphere Business Space 6.2. Inter-widget communication is an important capability that enables various widgets to work together to realize complex scenarios and to gain more business value. In accordance with the IBM iWidget specification, widgets communicate using events. The ECM Widgets make the best use of this mechanism and provide a set of flexible interfaces to communicate with third-party widgets. Business analysts can create their own widgets or use existing widgets to communicate with the ECM widgets to meet their business needs.

Understanding widget communication

Widgets communicate using events. A sending widget publishes an event, and the receiving widgets accept and process the event. The payload of an event carries messages that are sent between the sending widget and the receiving widget, as shown in Figure 1.

Figure 1. Widget communication
Drawing of Widget A containing a Published Event pointing to Widget B containing a Handled Event

A payload is a carrier that transfers data from published events to receiving events and is defined by a payload definition, such as payloadDef. A payload can:

  • Be a primary element type, such as a string or a number.
  • Have a complex structure composed of other payloads.
  • Behave like an object.
  • Be declared as any, which means it can contain any type of data.

Both the event and the payload are defined in the widget definition XML files. For example, imagine you have two widgets. The Book List Widget displays a book list. The Book Details Widget displays the selling trend and details according to the book serial number or other information the payload passes on. The Book payload is composed of three other simple payload definitions of type string: sn, name, and author. The example event and payload definitions in the XML are shown in Listings 1 and 2. See Download for all the listings from this article.

Listing 1. Book List Widget
<iw:payloadDef name="Book">
    <iw:payloadDef name="sn" type="string" defaultValue="" 
    description="The serial number of a book"/>
    <iw:payloadDef name="name" type="string" defaultValue="" 
    description="The name of a book"/>
    <iw:payloadDef name="author" type="string" defaultValue="" 
    description="The author name of a book"/>

<iw:event id="Send Book Info" published="true" 

<iw:eventDescription id=" SendBookInfoDescription" payloadType="Book" 
description="" lang="en"/>
Listing 2. Book Details Widget
<iw:payloadDef name="Book">
    <iw:payloadDef name="sn" type="string" defaultValue="" 
    description="The serial number of a book"/>
    <iw:payloadDef name="name" type="string" defaultValue="" 
    description="The name of a book "/>
    <iw:payloadDef name="author" type="string" defaultValue="" 
    description="The author of a book"/>
<iw:event id="Receive Book Info" handled="true" onEvent="handleReceiveBookInfo" 
<iw:eventDescription id="ReceiveBookInfoDescription" payloadType="Book" 
description="" lang="en"/>

An event definition consists of two parts: an event and an eventDescription. An event can be a published event or a receiving event, which is indicated by the published or handled attribute in its definition. When you define payloads and events, the eventDescName property of an event refers to the id property of an eventDescription. The payloadType property of an eventDescription refers to the name property of a payloadDef. These references connect all the pieces into a complete definition. Figure 2 shows the relationship between payloads and event definitions.

Figure 2. Widget event and payload
Drawing of iw:event containing id, eventDescName, and published/handled, pointing to iw:eventDescription containing id, payload Type, and description, pointing to iw:payloadDef containing name, type, and defaultValue

A receiving event defines its handling function. For the Receive Book Info event in Listing 2, its handler is handleReceiveBookInfo, which is a JavaScript function. This function must be defined in the widget code.

The IBM WebSphere® Business Space provides a convenient way to interconnect widget events at runtime using a process called wiring. Figure 3 shows a screen shot of the wiring user interface in the IBM WebSphere Business Space 6.2.

Figure 3. Widget wiring interface in IBM WebSphere Business Space 6.2
Screen cap: Widget Wiring window showing wires for Book Details and a flow from Book List to Send SN to Receive SN to Book Details

When the wiring process is complete, a published event and a handle event are linked together.

Using the ECM Widgets event framework and interface

As Part 1 describes, ECM Widgets offers a set of widgets, including in-basket, step completion, header, attachment, and work data, to build BPM solutions. All of these widgets comply with the iWidget specification. Each widget provides an events interface to communicate internally or with third-party widgets.

Most of the ECM Widgets event IDs follow a consistent naming convention: Send{Payload Type} for published events and Receive{Payload Type} for handled events. In a typical BPM solution, an in-basket widget is wired with a step completion widget using a published event (Send Work Item Id) and a handled event (Receive Work Item Id) with a WorkItemId payload. In another example, a step completion widget might be wired with a work data widget and with attachment widgets with the WorkItem payload using one of the following published events:

  • Send Work Item
  • Send Save Work Item
  • Send Close Work Item

And using the corresponding handled events:

  • Receive Work Item
  • Receive Save Work Item
  • Receive Close Work Item

Most of the published and handled events from ECM Widgets support automatic wiring, which means that manual wiring actions are not necessary for these events, including the scenarios mentioned in the previous paragraph. Although these events support automatic wiring among ECM Widgets, they can also be manually wired to third-party widgets. Some events are provided specifically for third-party integration, such as the Receive Search Values event in a content list widget and the Receive Role event in an in-basket widget, which receives payloads from third-party widgets.

Figure 4 shows the communication using events among widgets in the ECM Widgets 4.5.1 release, including published and receiving events and the payload.

Figure 4. ECM Widgets 4.5.1 event framework
Drawing of workflows

Exploring a sample widget

This section shows how to develop and enable an example widget to communicate with the ECM Widgets. The example widget contains a publishing event and handled events. It connects the in-basket widget and the content list widget from the ECM Widgets 4.5.1 release by obtaining payloads from the in-basket and sending them to the content list.

In ECM Widgets 4.5.1, the in-basket widget has a series of published events called Send {field name} that are generated dynamically according to the columns the in-basket widget displays. Assume you have a workflow definition, and the fields in it can provide information such as a person's name, year, and so on. After the workflow is launched, the in-basket widget can display these fields in its columns, and then it can provide the dynamic events to send the values of each field out to a receiving widget.

The content list widget enables you to fetch a list of documents using search in an IBM FileNet Content Engine. If the content list widget is wired to another widget's publishing events, the content list widget can execute the search with search criteria the user passed in.

To take advantage of these features, the example widget is called Paper Seeker. This widget has two functions:

  • A function to obtain and display a person’s name and the year information from a workflow using the in-basket widget’s publishing events.
  • A function to provide a button to send information to the content list widget as input.

Typically, each widget has an XML file and a JavaScript file to provide definitions that describe their behaviors. The XML file has four main parts:

  • The resource files to which the widget refers
  • The payload definition
  • The event and event description definition
  • The widget content

Listing 3 shows the widget's XML coding, including comments explaining the details (see also Download).

Listing 3. PaperSeeker.xml
<iw:iwidget name="PaperSeeker" xmlns:iw=""
iScope="sample.widget.PaperSeeker" allowInstanceContent="true" 
supportedModes="view" mode="view">
    <!-- Resource references -->
    <iw:resource uri="PaperSeeker.js"/>

    <!-- Payload definition section -->
    <iw:payloadDef name="Author" type="string" defaultValue="" description=""/>
    <iw:payloadDef name="PublishYear" type="number" defaultValue="" 

    <iw:payloadDef name="PaperInfo">
      <iw:payloadDef name="Author" type="string" defaultValue="" description=""/>
      <iw:payloadDef name="PublishYear" type="number" defaultValue="" 
    <!-- Event definition section -->
    <!-- Receive Author is used to wire with in-basket to 
    get a person's name as an Author. The handleReceiveAuthor method in PaperSeeker.js 
    will handle the payload passed in.-->
    <iw:event id="Receive Author" handled="true" 
    eventDescName="ReceiveAuthorDescription" />
    <iw:eventDescription id="ReceiveAuthorDescription" 
    payloadType="String" description="Receive Author event" lang="en"/>
    <!-- Receive Publish Year is used to wire with in-basket to get the year 
    information to populate Publish Year. The handleReceivePublishYear method in 
    PaperSeeker.js will handle the payload passed in.-->
    <iw:event id="Receive Publish Year" handled="true" 
    eventDescName="ReceivePublishYearDescription" />
    <iw:eventDescription id="ReceivePublishYearDescription" 
    payloadType="String" description="Receive Publish Year event" lang="en"/>

    <!-- Send Paper Info is used to wire with Content List to send the 
    PaperInfo payload as the input -->
    <iw:event id="Send Paper Info" published="true"
    <iw:eventDescription id="SendPaperInfoDescription" 
    payloadType="PaperInfo" description="Send PaperInfo event" lang="en"/>

    <!-- Initial widget content -->
    <!-- _IWID_ is a placeholder to be replaced with the actual ID dynamically to 
    avoid ID duplication -->
    <iw:content mode="view">
        <div id="_IWID_view">
            <div><b>Author: </b><input type="text" 
            <div><b>Publish Year: </b><input type="text" 
            <input type="button" id="_IWID_seeker" name="seeker" value="Seek Paper" 

The JavaScript file has functions that define the widget's behavior, including publishing or receiving events. In IBM mashup platforms, the dojo class format is used. The JavaScript file in Listing 4 illustrates these functions (see also Download).

Listing 4. PaperSeeker.js

dojo.declare("sample.widget.PaperSeeker", null, {

    onLoad: function() {
        //this.iContext.widgetId is generated by the Mashup container at runtime
        this.domID = "_" + this.iContext.widgetId + "_";

    //to handle Receive Author event
    //populate the author field with payload received
    handleReceiveAuthor: function(iEvent) {
            dojo.byId(this.domID + "author").value = iEvent.payload;

    //to handle Receive Publish Year event
    //populate the publishYear field with payload received
    handleReceivePublishYear: function(iEvent) {
            dojo.byId(this.domID + "publishYear").value = iEvent.payload;
    //invoke when the button is pressed
    //send Paper Info event will be fired with a proper payload
    seekPaper: function(){
        var author = dojo.byId(this.domID + "author").value;
        var publishYear = dojo.byId(this.domID + "publishYear").value;
        var payload = [{"name": "Author", "value": author},
            {"name": "PublishYear", "value": publishYear}];
        this.iContext.iEvents.fireEvent("Send Paper Info", "any", payload);

Deploying and wiring widgets in IBM WebSphere Business Space 6.2

This section describes how to deploy, wire, and register widgets.

Register the example widget

To make the example widget available in the WebSphere Business Space 6.2 server, complete the following steps.

  1. Register the example widget with the Business Space, as shown in Figure 5.
Figure 5. Register widget definition
Screen cap of BSpaceManager.war\registryData directory and selecting DWSampleWidgets.xml
  1. Prepare a registry file as shown in Listing 5 (see also Download).
Listing 5. Registry file DWSampleWidgets.xml
<tns:BusinessSpaceRegistry xmlns:tns="" 
BusinessSpaceRegistry.xsd ">
    <tns:name>DW Sample Widgets</tns:name>
    <tns:name>Paper Seeker</tns:name>
    <tns:description>A widget to seek papers.</tns:description>
    <tns:tooltip>Paper Seeker</tns:tooltip>
    <tns:serviceEndpointRef required="true">
  1. Save the registry file in the {Business Space deploy folder}\registryData folder as shown in Figure 6.
Figure 6. Deployment
Screen cap of PaperSeeker.js and PaperSeeker.xml files in the DWSampleWidgets_war.ear/DWSampleWidgets.war/src/sample/widget folder
  1. Package the widget code into a war file and deploy it on the server. The new widget is available in the Business Space environment, as shown in Figure 7.
Figure 7. Widget registered successfully
Screen cap: Window showing DW Sample Widgets and now containing Paper Seeker widget

Configure the in-basket widget

Before applying the new widget, you need to configure the in-basket widget and the content list widget. Complete the following steps.

  1. Use the Process Designer to define a workflow that contains the name and the year fields. The assumption here is that you have already created the workflow for this sample. The workflow contains pre-defined fields as shown in Figure 8.
Figure 8. Pre-defined workflow fields
Screep cap: Workflow Properties window with Data Fields tab showing the Author string field and the PublishYear string field highlighted
  1. Create an in-basket with the two fields exposed in the Process Configuration Console (refer to Part 2 for details).
  2. Create an application space or update an existing application space, such as DefaultApplication, to define a role in the new in-basket.
  3. Configure the ECM Widgets In-basket widget to show the new in-basket widget by setting the application space name, as shown in Figure 9.
Figure 9. Apply the application space
Screen cap: In-basket window with Change Application Space window overlayed and DefaultApplication is typed into the Application Space Name field
  1. Assign the role you defined, as shown in Figure 10.
Figure 10. Apply the role
Screen cap: In-basket window with Indexer defined as the role

Configure the content list widget

To configure the content list widget, you need to plan and define a Workplace XT stored search with the Search Designer tool and to configure the content list widget with the stored search URL that Workplace XT provides. In general, a stored search has one or more search criteria, result columns, and other settings. The content list widget can execute with predefined search criteria in the stored search definition, or it can execute by substituting the editable search criteria dynamically if it is wired with a sender widget.

To accomplish this, the content list widget provides a Receive Search Values event. The format of the payload is an array of key values. The content list parses the payload and uses the key values to compare with the stored search criteria. If there is a match, the content list uses the values from the key to replace the predefined value in the stored search. The content list widget then executes a search with the new values.

For example, you have a payload published in your example widget: [{"name": "author", "value": "Mike Mahomet"}, {"name": "publishYear", "value": 2000}]. This payload replaces the search criteria author and publishYear in the stored search.

Complete these steps to configure the example content list widget:

  1. Define a stored search in the Search Designer with the search criteria shown in Figure 11.
Figure 11. The stored search definition
Screen cap: Workplace XT Search Designer window showing Stored Search dropdown field and Search Criteria tab highlighted. Author is set to be like the value of a, and PublishYear is equal to the value of 1.
  1. Go to the Workplace XT, and determine the content URL of the stored search definition.
  2. Copy the hyperlink into the content list widget configuration panel, as shown in Figure 12.
Figure 12. Configure content list widget
Screen cap: Content List window containing the Workplace XT URL in the URL Address for Stored Search field
  1. Save the information. The content list widget can now use the default criteria to execute the search.

Widget wiring

Complete the following steps to wire the widgets together.

  1. Drag and drop the new widget into the same page as the existing in-basket widget and content list widget.
  2. Select Widget Wiring, as shown in Figure 13.
Figure 13. Widget wiring
Screen cap: Your Business Space window containing the DW Example tab, and Widget Wiring is highlighted in the dropdown menu
  1. On the Widget Wiring window, wire the in-basket's Send Author event with the example's Receive Author event, as shown in Figure 14.
  2. Wire the in-basket's Send PublishYear event with the example Receive Publish Year events, as shown in Figure 14.
Figure 14. Wiring 1
Drawing of an In-basket box pointing through Send Author and Receive Author to Paper Seeker. In-basket box also points through PublishYear and Publish Year to Paper Seeker
  1. Wire the example Send Paper Info event with the content list's Receive Search Values event, as shown in Figure 15.
Figure 15. Wiring 2
Drawing of a Paper Seeker box pointing through Send Paper Info and Search Values to a Content List box

Now the widgets have been wired.

Running the example

Complete the following steps to run the example:

  1. Select a row in the in-basket by clicking it. You can see the Paper Seeker example has the Author and PublishYear values on the display.
  2. Click the Seek Paper button. A search is executed with input values from the Paper Seeker. The result is displayed in the content list widget, as shown in Figure 16.
Figure 16. Play the example
Screen cap: In-basket displaying the Publish tabe and Papers 1 and 3 details. Also shows Paper Seeker windows with Mike as author and 1999 as Publish Year.


This is the final part of the three-part series introducing the ECM Widgets. In this part, you saw a broad overview of the event mechanism, of the IBM iWidget specification, and of the ECM Widgets event interfaces. You also used an example to learn how to write a widget and how to wire it with the ECM Widgets to gain more value.


Thank you to following people for reviewing this article:

  • Lauren Mayes, the architect of ECM Widgets
  • Ming Liang Guo, team lead of the ECM Widgets development team
  • Simon Chu, IBM Master Inventor


Sample widget codes for this articleSample.zip5KB





developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Information management on developerWorks

Zone=Information Management
ArticleTitle=Build FileNet BPM applications using IBM ECM Widgets, Part 3: Expanding ECM Widgets using third-party widgets