Integrate third-party widgets with IBM ECM Widgets, Part 1: Integration with the In-basket widget

Develop a role selector widget to integrate with the In-basket widget

The IBM® Enterprise Content Management Widgets (ECM Widgets) product is gaining traction in banking, insurance, health care, and many other fields. The ease of use and programming-free nature of the widgets enable business application developers to quickly produce content management applications. For industry solutions that require customized widgets, developers can build new widgets to meet their own business requirements. These customized widgets can be easily integrated into the ECM widgets environment by events wiring. In this article series, learn how to develop custom widgets to integrate them with four ECM widgets to build powerful solutions. Part 1 details how to use events of the In-basket widget and how to develop a role selector widget to work with the In-basket widget.


Shao Hong Xu (, Software Engineer, IBM  

Shao Hong Xu photoShao Hong Xu is a software developer in the IBM China Development Lab. He has extensive experience in developing for the IBM FileNet product and in Web 2.0 application development based on Dojo.

15 July 2010

Also available in Chinese


ECM Widgets is a new Web 2.0 application based on mashup technology. As an important part of the IBM FileNet® P8 product, ECM Widgets provides several widgets developers can use as-is or can customize to easily create content-centric business process applications for FileNet P8. IBM ECM Widgets 4.5.2 is enhanced in both functions and events to enable users to more easily and flexibly build BPM solutions. This first article in this series introduces how to develop a role selector widget to work with the In-Basket widget.

In-basket events overview

Table 1 shows the events supported by an In-basket widget from the 4.5.2 release. You can integrate these events together to develop your own widgets to more closely meet the needs of your business. The In-basket widget, as a receiver, can handle events sent by other widgets. As a sender, it can also send events to other widgets. The payload of each event is a data interface between the two widgets. The developer needs to know the payload format as well. As for the receiving payload, you can refer to Table 1 to obtain detailed information. As for sending payload, you can wire the In-basket widget and the Script Adapter widget (Business Space's own widget) together. The Script Adapter widget will automatically parse the payload of the event sent by the In-basket widget.

Table 1. In-basket events overview
Event nameDescriptionEvent typePayload
Change roleShow the in-baskets associated with the role.receive{name:"roleName"}
Work item openedThe user opened a work item. This event is automatically wired to the Step Completion widget.send---
Row selectedThe user selected a work item.send---
RefreshRefresh the work items in the in-basket. This event is automatically wired to the Step Completion widget.receive{}
In-basket selectedThe user selected an in-basket.send{}
Request selected rowsSend the widget's selected rows in the Send selected rows event.receive{}
Send selected rowsSelected rows are sent in this event when the widget receives the Request selected rows event.send{}
Custom actionUser can customize the event.send{}

Let's take a look at an example change role event to understand how to leverage it to build a role selector widget.

Customer requirements

XYZ company has several dozen roles that belong to various application spaces. Many end-users have several different roles for handling different levels of responsibility. All end-users will use the same business space and pages to handle their work. XYZ company's business analyst will design a suite of business spaces and pages, and share them with end-users. In order to reduce the maintenance effort, the business analyst will not give end-users the configuration access to any page. So when end-users wish to pick up different work items according to their own roles, they would not be able to select any role in the In-basket widget because of the access restriction. One possible solution is to ask the business analyst to create a space for every role and share the space with end-users who belong to that role. This turns out to be a huge effort for the business analyst. A better alternative is to use a role selector widget (discussed in the next section).

Developing a role selector widget

Figure 1 shows the visual design for the widget. A user can input an application space name and click on the Retrieve roles button. If the application space is active, a role list will be returned and displayed in a Dojo ComboBox. Otherwise, an error message such as "Invalid application space message" will pop up. Users can select one item in the role list and click on the Submit button to pass the role to a targeted In-basket widget.

Figure 1. Role selector widget
Role selector widget

Wiring widgets

The In-basket widget receives a role through the change role event. The payload of the event is a role name, as shown in Listing 1:

Listing 1. Role payload
<iw:payloadDef name="Role">
	<iw:payloadDef defaultValue="" description="" name="name" type="string"/>

The role selector widget defines a send role event to send a role name to an In-basket widget. Listing 2 shows the event definition in a RoleSelector.xml.

Listing 2. Send role event defined
<iw:event id="Send Role" published="true" eventDescName="SendRoleDescription"/>
<iw:eventDescription id="SendRoleDescription" description="Send Role" lang="en"/>

The two widgets are connected by wiring the change role event of an In-basket to the send role event of a role selector, as illustrated in Figure 2. After the widgets are wired, the communication channel between the two widgets is built up. The In-basket widget can handle the event from role selector widget.

Figure 2. Wiring an In-basket widget and a role selector widget together
Wiring an In-basket widget and a role selector widget together

Invoking a send role event

Business Space, which is a mashup container, provides one API method fireEvent() for sending events. Listing 3 shows how to invoke this method.

Listing 3. Invoking the send role event
SendEvent: function() {
	//An example payload is {name:"SampleIndexer"};
	var payload={name:"SampleIndexer"};
	this.iContext.iEvents.fireEvent("Send Role", "any", payload);

Note: There is a prerequisite to using the In-basket widget to change role using a change role event—no role is manually configured in the In-basket widget.

Retrieving the role list

When a user clicks on the Retrieve Roles button (illustrated in Figure 1), a role selector widget will invoke the PE REST API to fetch all roles belonging to the corresponding application space. The process contains the following three steps:

  1. Get base REST URI.

    Role selector uses the same base REST URI as ECM Widgets. ECM Widgets relies on the user's input in the browser to replace protocol, host name, and port in the URI and store it into ecmwdgt.settings.bpmServiceBaseURL. For example, if you input https://demo1:9444/mum/enabler to log in to Business Space, the base REST URI will be https://demo1:9444/WorkplaceXT/P8BPMREST/p8/bpm/v1. Listing 4 shows how to fetch the base REST URI.
    Listing 4. Get base REST URI
    getBaseRESTURI: function() {
    	return ecmwdgt.settings.bpmServiceBaseURL;
  2. Locate REST resource.

    The resource for list of roles within an application is /p8/bpm/v1/appspaces/{appspace}/myroles. The parameter is the name of the application space, and the application HTTP method is GET. All of PE REST service resources can be found in the FileNet P8 documentation.
  3. Call PE REST service.

    Now, the whole REST URI is available by concatenating the base URI and the rest resource. It will be used to invoke the PE REST service. An example of the whole URI can be found in this link: https://demo1:9444/WorkplaceXT/P8BPMREST/p8/bpm/v1/appspaces/sampleApplication/myroles.
    Listing 5. Get base REST URI
    RetrieveRoles: function() {
    	this.applicationSpace = this.appSpaceTextBox.value;
    	//Get PE REST base URL
    	var baseRestURL = ecmwdgt.settings.bpmServiceBaseURL; 
    	//Concat whole REST resource URL
    	var roleURI = baseRestURL + "/appspaces/" + this.applicationSpace + "/myroles";
    	//Update the application space used by ECM Widgets
    	ecmwdgt.settings.applicationSpace = this.applicationSpace;
    		url: roleURI,
    		handleAs: "json",
    		sync: false,
    		load: dojo.hitch(this,function(response) {
    			this.createDataStore(response); = this.rolesDataStore;
    		error: dojo.hitch(this,function(response) {
    		var errorMessage = "Application Space " + this.applicationSpace + 
    			" is not found"; = [];

    After the role list is returned, it can be used to create a data store and assign the data store to roleComboBox. Users can select a role in the ComboBox and click on Submit button to pass the role to the In-basket widget.

Deploying the role selector widget

The following steps outline building and deploying a role selector widget to be operational with the IBM ECM Widgets 4.5.2:

  1. Package the widget zip file. Download to get the detailed package structure. The catalog_RoleSelectorWidget.xml and RoleSelectorWidgetEndpoints.xml files are used to provide information to register the widget in the business space. Please note, the name of the catalog file must start with a prefix "catalog_".
  2. Deploy the widget by issuing the following commands, modifying the parameters according to your environment.
    Listing 6. Deploy commands
        C:\> cd <WAS_install_path>\profiles\<profile_name>\bin
        C:\> wsadmin -connType NONE
        C:\>$AdminTask installBusinessSpaceWidgets {-serverName server1 -nodeName 
        WMADBS7Node01 -widgets C:\}
  3. Restart IBM WebSphere® Application Server. You will see the widget in the widgets palette:
    Figure 3. Role selector widget in widgets palette
    Shows role selector widget as one of the widgets in the work space

Using the role selector widget

The following steps show how a business analyst would create a business space, add the role selector widget into a mashup page, and share the space with end users:

  1. Create a space and a mashup page, and drag the role selector widget and In-basket widget onto the mashup page.
    Figure 4. Add role selector and In-basket widgets
    Add role selector and In-basket widgets
  2. Wire the In-basket widget and the role selector widget together. (Refer to Figure 2 above.)
  3. Share view access of the space with end users, such as "Joe."
    Figure 5. Share the space
    Shows selecting to share the space
    Figure 6. Select end user
    Shows adding Joe
  4. When Joe logs in to the Business Space, enters an application space, such as DefaultApplication, and clicks on the Retrieve Roles button to fetch the role list, the role will be returned to the application.
    Figure 7. Retrieve Role list
    Retrieve Role list
  5. If the application space is invalid, an error message will pop up, as shown in Figure 8:
    Figure 8. Invalid application space
    Invalid application space
    Figure 9. Render In-baskets
    Render In-baskets


Part 1 of this series has described the In-basket widget events in detail. Then, by using an example of one customer requirement, this article has shown how to develop, deploy, and use a role selector widget to meet the requirement. After reading this article, developers should have a good understanding of the events of the In-basket widget and be ready to start building their own widgets.

In Part 2 of this series, learn how to integrate third-party widgets with the Content List widget.


Thanks to Simon Chu for reviewing this article. He is an IBM Master Inventor and has been a great mentor.


Role Selector widget source codeWidgets_RoleSelector.zip5KB



Get products and technologies

  • Build your next development project with IBM trial software, available for download directly from developerWorks.



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=Integrate third-party widgets with IBM ECM Widgets, Part 1: Integration with the In-basket widget