Using Click-to-Action to Provide User-Controlled Integration of Portlets

This article describes, and tells how to use, a new WebSphere Portal feature, called Click- to-Action, that provides automatic front-end integration of portlets.

Amber Roy-Chowdhury (, Senior Software Engineer, IBM

Amber Roy-Chowdhury is a Senior Software Engineer at IBM Raleigh Lab. Amber is currently involved in WebSphere Portal architecture and development, and has for the past several years architected and developed distributed system middleware, including portions of the WebSphere Application Server. Amber holds a Ph.D from the University of Illinois, Urbana. You can contact him at

Shankar Ramaswamy (, Senior Software Engineer, IBM Raleigh Lab

Shankar Ramaswamy is a Senior Software Engineer at IBM Raleigh Lab. Shankar is an architect for WebSphere Portal, and holds a Ph.D from the University of Illinois, Urbana. You can contact him at

Xinyi Xu (, Staff Software Engineer, IBM Raleigh Lab

Xinyi Xu is a Staff Software Engineer at IBM Raleigh Lab. Xinyi is currently involved in WebSphere Portal development. Xinyi holds a Master's degree from the University of Massachusetts, Amherst. You can contact her at

16 December 2002


This article describes, and tells how to use, a new WebSphere Portal feature called Click- to-Action (hereafter called C2A) that provides automatic front-end integration of portlets. Using C2A, users can transfer data from one portlet to another, and have the target portlet react to the data, causing information on the page to be refreshed. C2A also provides the abilities to let the user, using a single click, broadcast a data item from one portlet to all matching actions on the page, and to scatter multiple related data items to multiple actions on multiple target portlets on the page. We use the term source for such portlet-contributed data items which may be transferred to target portlets.

C2A helps users be more productive because they don't have to discover which actions are available on target portlets on the current page, and they don't have to manually copy and key in data from sources to targets. C2A helps users rapidly navigate across independently developed applications and view related data in each application.

You can download the C2A package for WebSphere Portal 4.1 from the WebSphere Portal catalog. The package contains runtime classes, JSP tag libraries and javascript libraries which must be installed to make C2A work, together with install and configuration instructions. The package also contains samples demonstrating C2A usage. The discussion in this article is tied to one of the samples shipped with the package.

The C2A runtime uses type information to match sources with compatible targets, and inserts clickable icons associated with sources on portlet pages. When the user clicks on an icon next to a source, he or she is presented with a pop-up menu containing the list of targets. When the user selects a target, the C2A runtime delivers the source data to the target in the form of the corresponding portlet action. The portlet does not know the difference between an action initiated by user interaction with its own page segment versus one initiated using C2A. Therefore, portlet programmers can follow the normal portlet programming model.

This article includes a scenario and screen shots to more clearly illustrate the benefits which C2A offers. It tells you how to enable portlets to contribute source data or target actions for C2A and provides some programming guidelines. Next, it provides an overview of C2A concepts and its architecture. Finally, it discusses possible future directions of C2A and concludes.

The Order and Shipment Tracking scenario

Friendly Electronics Corporation is a fictitious manufacturer of hi-tech equipment and often receives inquiries from customers about their orders. Friendly wanted to empower its customer account representatives with an "Order Status" portal page, which would let them provide customers with order-related information in a fast and accurate manner.

Therefore, Friendly built an Order Status portal page. It contained several portlets, which connect to several back-end systems to get information about customer orders.

Table1. Portlets on Order Status portal page

PortletBack-end systemData returned
Order SummaryFriendly's orders databaseAll orders by month, including order ID and customer ID
Order DetailsFriendly's orders databaseDetails about a specific order
Customer DetailsFriendly's CRM systemDetails about a specific customer
Account DetailsFriendly's accounts databaseAccounts information for a specific order
Tracking DetailsExternal shipment vendor's tracking databaseOrder routing and delivery information

Table 1 lists the portlets comprising Friendly's Order Status portal page.

Initial user interaction

The Order Status entry page is shown in Figure 1. The account representative must interact individually with each portlet on the page.

Figure 1: A view of the Order Status entry page
Order Entry page

For example, to get details about a single order, an account representative must select a row in the Order Summary portlet listing, key the order ID from the row in the Order Details portlet's entry textbox, and submit the query by clicking on the "Submit" button. The page refreshes with details about the order.

Next, if he wishes to view the accounts receivable for the order, he must key in the same order ID in the Account Details portlet and submit the query. He has to repeat these actions for the customer ID and other data items appearing on the page before all portlets on the page show information pertaining to the same order.

Figure 2 shows the Order Status portal page after the account representative has entered an order ID from the Order Summary portlet into the Account Details and the Order Details portlets. These portlets now display detailed information pertaining to the order ID, while the other two portlets still show their entry panels.

Figure 2: A view of the Order Status results page
Order Status results

Improved user interaction

Friendly Corp. would like to simplify this task for their account representatives. They could do this if they had a mechanism that would facilitate interaction among the Order Status portlets by enabling easy transfer of compatible data between them.

For example, Friendly would like to enable a customer account representative to click on a specific order ID or customer ID in the Order Summary portlet and trigger a transfer of data to one or more of the other portlets on the page, causing them to display details on the order ID or customer ID.

Using pre-configured interaction options between portlets would eliminate the manual observation and entry of bits of data from one portlet's view into another's entry field. It would also simplify the account representative's learning process, reduce errors, and speed up the process of getting all information about a single order. A menu-driven interface based on C2A technology, is shown in Figure 3. When the account representative clicks on the arrow icon next to an order ID in the Order Summary portlet, as shown in Figure 3, a menu of target portlet actions that could react to the order ID displays. The Order Details action (on the Order Details portlet) and the Account Details action (on the Account Details portlet) are valid destinations for an order ID.

Figure 3: Portal page with C2A-enabled portlets and menu of matching actions
Order Status results

Additional features

Using the Broadcast action corresponds to choosing all the actions in the menu at once. The result of selecting Broadcast is shown in Figure 4. The result is the same as the result shown in Figure 2, but it has been achieved in an easier, more intuitive, and less error- prone manner.

Figure 4: Portal page after user has used C2A to broadcast the order ID
Order Status results

C2A can also scatter related bits of data from a single source portlet to compatible target actions on the page. The icon generating the Broadcast All Sources pop-up menu item, shown in Figure 5, may be used to transfer the order ID from the row to the Order Details and Account Details portlets, and the customer ID from the row to the Customer Details portlet.

Figure 5: Portal page view illustrating the C2A scatter menu action
Order Status results

The results of the selection are shown in Figure 6. Several portlets on the page display information about the same order; the scatter feature synchronized the information on multiple portlets on the page through a single user click.

However, the Tracking Details portlet does not show data consistent with the current order. The user must perform another menu driven interaction to populate the tracking details because the tracking ID information which it needs was not available until the Order Details portlet retrieved the current order details. We plan to address such chained propagation of information between portlets in the C2A model in future releases.

Figure 6: Portal page view showing results of user choosing C2A scatter action
Order Status results

Applying C2A to the portlet application provided an improved user experience. The customer account representative increased productivity by using an easy, menu-driven access to relevant information about a single item (in this case, an order). As we shall see in the following sections, the benefits which C2A brings are achieved through a set of easy enablement steps.

Enabling portlets to use C2A

To enable a portlet to be a source of data, you use a custom JSP tag library, provided with the C2A install package, to flag sharable data on its output pages. You specify a data type and a specific value for each source using JSP tags.

To enable a portlet to be a target, you describe a subset of the portlet actions, including type information for the action parameters. You use Web Service Definition Language (WSDL) with some custom extensions to describe the actions.

Source portlets

For portlets which can provide source data for C2A, you insert tags from a custom JSP library into the JSPs that the portlet uses to render data. The custom tag library is provided as part of the C2A runtime.

On the basic tag, encodeProperty, you specify the type, namespace, and value associated with the source. The namespace is used to group related types together, so inadvertent matches between similarly named types in unrelated application domains may be avoided. The (type, namespace) tuple is used by the C2A runtime to match sources with compatible actions (those that can consume parameters of the same type). In the value attribute you specify a string which contains the value to be transmitted.

A clickable icon is generated at the point the encodeProperty tag is inserted. When clicked, the icon generates a menu of actions compatible with the source. You can use additional attributes on the tag to specify advanced options, such as broadcast. Most attribute values can be specified dynamically, i.e. using runtime expressions.

You use an additional tag, encodeProperties, to provide the scatter capability. This may be used to enclose several encodeProperty tags, each of which is used to contribute a single source data object for the scatter. At the point where the encodeProperties tag is closed, a clickable icon is inserted to trigger the scatter.

Listing 1 shows an example use of the encodeProperty tag used to create the clickable icon corresponding to an order ID. You can obtain more details about the C2A tags from the documentation and sample code provided with the product.

Listing 1: Example of encodeProperty JSP tag

<%-- The following line of code includes the tag library --%> 
<%@ taglib uri="/WEB-INF/tld/c2a.tld" prefix="C2A" %> 
<td align="center" > 
<%-- The following tag identifies the source, and causes the Click-to-Action 
icon and the associated pop-up menu of compatible actions to be generated --%> 
<C2A:encodeProperty namespace="" 
type="OrderIDType" value="<%= orderId %>" /> 
<%= orderId %> 

Target portlets

You declare portlet actions, which can consume data transferred using C2A, in a WSDL file. WSDL is a language used to define collections of abstract operations, together with the parameters (called parts in WSDL) for each operation. Parameters for each operation are grouped into an input message (a collection of input parameters) and/or output message (a collection of output parameters). A concrete implementation of the abstract operation definitions may be specified using bindings. The binding includes the protocol and the data format to be used for invoking the operations - in essence, all the information an invoking program would need to invoke a concrete implementation of the operations. The language is extensible, and allows new bindings to be introduced to specify how to invoke custom implementations of the abstract operations. You can see the details from the WSDL Specification.

You must use a custom binding section to specify how to invoke the declared operations on the implementing portlet. The custom binding syntax is illustrated in Listing 2 and is described in detail in instructions accompanying the C2A download. The binding section maps each abstract operation to an action on the portlet. For each operation, the portlet action name must be provided. For each operation parameter, the action parameter name must be provided. Reasonable defaults apply for most attributes.

There are restrictions on the types associated with input parameters to C2A actions. These must be simple types declared using XSD (see the XSD Specification). Essentially, these are types whose values may be expressed as a simple string value, rather than a structure containing specific fields. For example, you can use simple types representing order IDs, customer IDs, last names, zip codes and so forth. However you cannot use structured, complex types such as an address (which may contain a name, a street, a city, and a zip code, for example). These restrictions will be addressed in future releases.

Listing 2 shows an example WSDL file for C2A, which corresponds to the Order Details portlet in the example. The namespace and type associated with the orderId parameter matches the source declaration using the encodeProperty tag in Figure 7. Therefore, if the corresponding source and target portlets were placed on the same page, the C2A broker would detect a match.

Listing 2: Example WSDL describing C2A target actions

<?xml version="1.0" encoding="UTF-8"?> 
<definitions name="OrderDetail_Service" 
  xmlns:tns=" " 
  <!-- all types must be simple types --> 
  <xsd:simpleType name="OrderIDType"> 
    <xsd:restriction base="xsd:string"> 
<message name="OrderDetailsRequest"> 
  <!-- only a single input parameter (part) is allowed --> 
  <part name="order_Id" type="tns:OrderIDType"/> 
<portType name="OrderDetail_Service"> 
  <operation name="order_Detail"> 
     <input message="tns:OrderDetailsRequest"/> 
<binding name="OrderDetailBinding" type="tns:OrderDetail_Service"> 
  <!-- the following indicates that a portlet implements the operations --> 
  <operation name="order_Detail"> 
    <!-- the name is the portlet action name, the caption is for display 
    in the menu, the description is for help about the action --> 
    <portlet:action name="orderDetails" caption="Order Details" description="Get 
details for specified order id"/> 
      <!-- the name is the portlet parameter name, partname is 
      the corresponding part name --> 
      <portlet:param name="orderId" partname="order_Id"/> 

The actions on the portlet are programmed following the normal portlet programming model, but need to follow some restrictions. First, the object used to encapsulate the action information when the portlet action is invoked must belong to the DefaultPortletAction class. Further, the action must expect a single input parameter delivered to it in the PortletRequest object. Refer to the Portlet Development Guide for details on programming portlet actions. The restriction specifying a single input parameter is reflected in the WSDL declaration - operations can only contain input messages with a single part.

These restrictions will be addressed in future releases. A code sample for the action for processing an order ID to obtain order details is shown in Listing 3.

Listing 3: Example WSDL describing C2A target actions

 public void actionPerformed (ActionEvent event) 
   //The action object must be an instance of DefaultPortletAction for actions 
   //which can be invoked through C2A 
   DefaultPortletAction action = (DefaultPortletAction) event.getAction(); 
   PortletRequest request = event.getRequest(); 
   if (action.getName().equals("orderDetails")) { 
     //This action could be invoked through C2A 
     //The single parameter, orderId is retrieved 
     String orderId = request.getParameter("orderId"); 
     //Process the orderId now or store it for later processing - code omitted 
   } //code for other actions omitted 

Programming guidelines

Since the C2A runtime does not incur much overhead in processing sources which do not have any matching actions on the page, and also does not generate the clickable icon, it is usually best to tag all sources in a portlet which meet the type restrictions. This maximizes the potential applicability of C2A as the same portlet is deployed in a variety of settings.

For example, a page containing various portlets supporting an auto insurance claims processing scenario would probably have information such as the driver's license number, policy number and auto make and model displayed by various portlets, together with actions for processing these in various ways. Each of these sources should be tagged for use by C2A as they can be represented using simple types.

For C2A targets, the actions declared for use by C2A must be invocable at any time. Because the set of actions associated with a target portlet is statically declared, the C2A runtime assumes that the same set is available in each request cycle. Also, it is best to code portlet actions so that they can be used for direct interaction with the portlet as well as for invocation through the C2A path.

Often, it may be possible to take an existing portet, examine its actions, and declare a subset of these which meet the C2A restrictions using WSDL, thus enabling the portlet to act as a C2A target.

C2A architecture

Figure 7 shows the high-level architecture of the C2A runtime. The C2A runtime consists of a generic wrapper portlet, used to wrap each C2A-enabled portlet, and a broker component. These components interface with the WebSphere Portal core runtime.

Figure 7. C2A architecture and flow
C2A Architecture

The wrapper intercepts calls to the application portlet. It also interfaces with the broker appropriately to transparently register actions declared by the portlet with the broker and transfer data from source to target portlets.

The broker maintains a central repository of actions on each portlet, together with parameter type information associated with the actions. It uses this information at runtime to perform source and target matches and generates the additional markup to render the clickable icon, generate the pop-up menu, and trigger the actions on the target portlet. An example of the generated markup, taken from the page displayed in Figure 3, is shown in Listing 4.

Listing 4. Example of generated C2A menu and action invocation markup

<!#x2014The following line includes the menuing library needed by c2a --> 
<script language="JavaScript" src='/wps/c2a/scripts/menu.js'></script> 
<td align="center" > 
    <!#x2014The following is generated by the c2a runtime to display the menu 
associated with a source --> 
    <script language="JavaScript"> 
        function func1(){ 
        window.Menu1 = new Menu(); 
        Menu1.formElementArray0 = new Array(1); 
        Menu1.formElementArray0[0] = "012001000000" 
        Menu1.addMenuItem('Order Details', 
        Menu1.formElementArray1 = new Array(1); 
        Menu1.formElementArray1[0] = "012001000000" 
        Menu1.addMenuItem('Account Details', 
        Menu1.formElementArray2 = new Array(1); 
        Menu1.formElementArray2[0] = "pb-action-data-1"; 
    <a href="javascript:void(0);" onclick="window.showMenu(window.Menu1, 
    <img src="/wps/c2a/images/c2a.gif" border=0 width=10 
<!#x2014The following forms are generated by the c2a runtime. There is one 
form corresponding to each menu action and is 
   dispatched when the user clicks on a menu action --> 
<form name="Order_Summary_c2a_broadcast_action_form" method="post" 
    <input type="hidden" name="c2a-data-reference" value=""/> 
    <input type="hidden" name="c2a-action" value="c2a-broadcast- 
<form name="Order_Details_orderDetails_form" method="post" 
    <input type="hidden" name="orderId" value=""/> 
    <input type="hidden" name="c2a-action" value="c2a-local-action"/> 
<form name="Account_Details_accountDetails_form" method="post" 
    <input type="hidden" name="orderId" value=""/> 
    <input type="hidden" name="c2a-action" value="c2a-local-action"/> 
<!#x2014The following code is generated by the c2a runtime and is executed 
when the browser loads the page. 
   It prepares the c2a menus on the page for display --> 
<script language="JavaScript"> 
function onLoad(){ 

The WebSphere Portal core runtime generates the portal pages, receives browser requests, invokes callbacks on portlets, and provides portlet related utilities and APIs used by the C2A broker and wrapper.

To understand the C2A flow better, you need to understand the basics of the portlet programming model, which is described in the Portlet Development Guide. The portlet programming model involves an event phase and a render phase in each request-response cycle. During the event phase, an action may be delivered on one portlet. If the portlet uses C2A , other actions, on other portlets, may be triggered. The event phase is followed by the render phase, during which each portlet returns markup, which is aggregated into a single page. The markup may include code for triggering actions on portlets. The page is then returned to the client (such as a browser).

A typical request-response flow involving C2A, illustrated in Figure 7, consists of the following steps:

  1. At portlet initialization time, the C2A wrapper processes any action WSDL file associated with the application portlet and registers the actions with the C2A broker.
  2. During the render phase of a request cycle, JSPs associated with C2A source portlets are processed. The custom C2A tags produce calls to the C2A broker, which examines the type information to determine matching actions. The broker generates additional code to create an icon to be used to display a pop-up menu of actions, and adds code to dispatch actions on portlets upon user selection from the menu (see Listing 4).
  3. After all render phase portlet callbacks are complete, the WebSphere Portal core assembles the response page and returns it to the client (for example, a browser).
  4. When the user clicks on the C2A icon for a source, he or she sees a menu of compatible actions (on the page) and selects one.
  5. The client, (for example, a browser) generates a new request containing the chosen source and action information and sends it to the WebSphere Portal Server .
  6. The WebSphere portal core delivers the action to the target portlet. The action is intercepted by the wrapper, which may interact with the broker to further process the request before delivering the action to the target.

All portlet actions are intercepted by the wrapper; however, actions which are invoked through direct interaction with the portlet (as opposed to interaction through the C2A menus) are passed through transparently to the portlet. In more advanced scenarios, such as the broadcast and scatter mentioned earlier, there will be more interactions between the wrappers and the broker to determine the appropriate target set and deliver the right data to the targets.

Future directions

The first version of the C2A function has been released for WebSphere Portal 4.1. There are several ways in which this function can be evolved to become more useful and easier to use.

At present, there are no tools specifically designed to make the incorporation of C2A capabilities into portlets easy. It would be useful to provide such tooling to aid in easy, GUI-driven C2A enablement of portlets.

At present, matching is restricted to actions on portlets on the same page as a C2A source, but it would be useful to support matching across pages, and matches on actions on external (non-portlet) entities such as Web Services.

The restrictions on parameters and types could be relaxed to accommodate a wider variety of actions invocable through C2A. Supporting chains of information propagation involving several portlets on the page in response to a user trigger would also be useful.

Finally, for programmers who seek maximum control over surfacing C2A sources and actions, a programmatic API would be required (in addition to the declarative approach currently supported), together with the capability to dynamically register and unregister sources and actions.


In this paper, we have presented Click-to-Action, a novel approach to user-driven front- end integration of portlets. The technology is simple to enable for the programmer, does not require custom programming, and allows the user to drive the integrated response of a set of independently created portlets. The technology is currently available on WebSphere Portal 4.1 as a Web download. The technology will be made easier to use in future releases, offer greater flexibility of implementation choices to the programmer, and expanded function.



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 WebSphere on developerWorks

ArticleTitle=Using Click-to-Action to Provide User-Controlled Integration of Portlets