Introduction

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.

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.

<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:payloadDef>

<iw:event id="Send Book Info" published="true" 
eventDescName="SendBookInfoDescription"/>

<iw:eventDescription id=" SendBookInfoDescription" payloadType="Book" 
description="" lang="en"/>

<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:payloadDef>
<iw:event id="Receive Book Info" handled="true" onEvent="handleReceiveBookInfo" 
eventDescName="ReceiveBookInfoDescription"/>
<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.

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.

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

Back to top

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.

Back to top

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).

<iw:iwidget name="PaperSeeker" xmlns:iw="http://www.ibm.com/xmlns/prod/iWidget"
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="" 
    description=""/>

    <iw:payloadDef name="PaperInfo">
      <iw:payloadDef name="Author" type="string" defaultValue="" description=""/>
      <iw:payloadDef name="PublishYear" type="number" defaultValue="" 
      description=""/>
    </iw:payloadDef>   
    
    <!-- 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" 
    onEvent="handleReceiveAuthor" 
    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" 
    onEvent="handleReceivePublishYear" 
    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"
    eventDescName="SendPaperInfoDescription"/>
    <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">
      <![CDATA[
        <div id="_IWID_view">
            <div><b>Author: </b><input type="text" 
            id="_IWID_author"><div>
            <div><b>Publish Year: </b><input type="text" 
            id="_IWID_publishYear"><div>
            <input type="button" id="_IWID_seeker" name="seeker" value="Seek Paper" 
            onclick="iContext.iScope().seekPaper()"/>
        </div>
      ]]>
    </iw:content>
</iw:iwidget>

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).

dojo.provide("sample.widget.PaperSeeker");

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) {
        if(iEvent.payload){
            dojo.byId(this.domID + "author").value = iEvent.payload;
        }
    },

    //to handle Receive Publish Year event
    //populate the publishYear field with payload received
    handleReceivePublishYear: function(iEvent) {
        if(iEvent.payload){
            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);
    }
});

Back to top

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.

2. Prepare a registry file as shown in Listing 5 (see also Download).

<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>sample.widget.RootId</tns:id>
    <tns:type>sample.widget.RootId</tns:type>
    <tns:version>1.0.0.0</tns:version>
    <tns:url>DWSampleWidgets/</tns:url>
    <tns:description></tns:description>
  </tns:Endpoint>
  <tns:Category>
    <tns:id>sample.widget.Category</tns:id>
    <tns:name>DW Sample Widgets</tns:name>
    <tns:description></tns:description>
    <tns:tooltip></tns:tooltip>
    <tns:order>99</tns:order>
  </tns:Category>
   <tns:Widget>
    <tns:id>sample.widget.PaperSeeker</tns:id>
    <tns:version>1.0.0.0</tns:version>
    <tns:name>Paper Seeker</tns:name>
    <tns:type>{com.ibm.bspace}iWidget</tns:type>
    <tns:description>A widget to seek papers.</tns:description>
    <tns:tooltip>Paper Seeker</tns:tooltip>
    <tns:categoryId>sample.widget.Category</tns:categoryId>
    <tns:widgetEndpointId>sample.widget.RootId</tns:widgetEndpointId>
    <tns:url>src/sample/widget/PaperSeeker.xml</tns:url>
    <tns:helpUrl></tns:helpUrl>
    <tns:iconUrl></tns:iconUrl>
    <tns:previewUrl></tns:previewUrl>
    <tns:previewThumbnailUrl></tns:previewThumbnailUrl>
    <tns:attachable/>
    <tns:owner></tns:owner>
    <tns:email></tns:email>
    <tns:serviceEndpointRef required="true">
      <tns:name>serviceUrlRoot</tns:name>
      <tns:refId>sample.widget.RootId</tns:refId>
      <tns:refVersion>1.0.0.0</tns:refVersion>
    </tns:serviceEndpointRef>
  </tns:Widget>
</tns:BusinessSpaceRegistry>

3. Save the registry file in the {Business Space deploy folder}\registryData folder as shown in Figure 6.

4. 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.

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.

2. Create an in-basket with the two fields exposed in the Process Configuration Console (refer to Part 2 for details).
   
   
3. Create an application space or update an existing application space, such as DefaultApplication, to define a role in the new in-basket.
   
   
4. 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.

5. Assign the role you defined, as shown in Figure 10.

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.

2. Go to the Workplace XT, and determine the content URL of the stored search definition.
   
   
3. Copy the hyperlink into the content list widget configuration panel, as shown in Figure 12.

4. 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.

3. 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.
   
   
4. Wire the in-basket's Send PublishYear event with the example Receive Publish Year events, as shown in Figure 14.

5. Wire the example Send Paper Info event with the content list's Receive Search Values event, as shown in Figure 15.

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.

Back to top

Conclusion

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.

Acknowledgments

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

Back to top

Download

Information about download methods

Resources

Learn

• Get more details about the ECM Widgets from the IBM ECM Widgets online document.
  
  
• Find out more about IBM iWidget Specification 1.0.
  
  
• Learn more about Information Management at the developerWorks Information Management zone. Find technical documentation, how-to articles, education, downloads, product information, and more.
  
  
• Stay current with developerWorks technical events and webcasts.
  
  

Discuss

• Check out the developerWorks blogs and get involved in the developerWorks community.
  
  

About the authors

Xin 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 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.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Understanding widget communication
• Using the ECM Widgets event framework and interface
• Exploring a sample widget
• Deploying and wiring widgets in IBM WebSphere Business Space 6.2
• Conclusion
• Download
• Resources
• About the authors
• Comments

Next steps from IBM

Rational products offer a complete collaborative lifecycle management set of tools for the IBM i platform for existing and new developers.

---

• Try: Download a free trial of Rational Developer for Power Systems, which provides an integrated development environment across the major platforms.
• Buy: Rational Developer for Power Systems

Dig deeper into Information Management on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers