Introduction

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.

Back to top

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.

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

Back to top

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

Back to top

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.

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:

<iw:payloadDef name="Role">
	<iw:payloadDef defaultValue="" description="" name="name" type="string"/>
</iw:payloadDef>

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.

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

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.

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; dojo.xhrGet({ url: roleURI, handleAs: "json", sync: false, load: dojo.hitch(this,function(response) { this.createDataStore(response); this.roleComboBox.store = this.rolesDataStore; }), error: dojo.hitch(this,function(response) { var errorMessage = "Application Space " + this.applicationSpace + " is not found"; this.roleComboBox.store = []; alert(errorMessage); }) }); }

   
   

   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.

Back to top

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 Widgets_RoleSelector.zip 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:\Widgets_RoleSelector.zip}

   
   
3. Restart IBM WebSphere® Application Server. You will see the widget in the widgets palette:
   
   Figure 3. Role selector widget in widgets palette
   
   
   

Back to top

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
   
   
   
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
   
   
   
   
   Figure 6. Select end user
   
   
   
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
   
   
   
5. If the application space is invalid, an error message will pop up, as shown in Figure 8:
   
   
   Figure 8. Invalid application space
   
   
   
   
   Figure 9. Render In-baskets
   
   
   

Back to top

Summary

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.

Back to top

Acknowledgment

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

Back to top

Download

Information about download methods

Resources

Learn

• Use an RSS feed to request notification for the upcoming articles in this series. (Find out more about RSS feeds of developerWorks content.)
  
  
• IBM ECM Widgets overview (IBM FileNet P8 Version 4.5.1 Information Center): Find details about the design and usage for ECM Widgets and the FileNet PE REST API.
  
  
• ECM Zone on developerWorks: Get the resources you need to advance your skills in IBM Enterprise Content Management topics.
  
  
• developerWorks Information Management zone: Learn more about Information Management. Find technical documentation, how-to articles, education, downloads, product information, and more.
  
  
• Stay current with developerWorks technical events and webcasts.
  
  

Get products and technologies

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

Discuss

• Participate in the discussion forum.
  
  
• Participate in developerWorks blogs and get involved in the My developerWorks community; with your personal profile and custom home page, you can tailor developerWorks to your interests and interact with other developerWorks users.
  
  

About the author

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

Rate this article

Comments

Back to top

Table of contents

• Introduction
• In-basket events overview
• Customer requirements
• Developing a role selector widget
• Deploying the role selector widget
• Using the role selector widget
• Summary
• Acknowledgment
• Download
• Resources
• About the author
• Comments

Dig deeper into Information 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