Realizing the value of IBM Business Process Manager in the WebSphere Portal environment, Part 2: The interaction between Coaches and portlets or widgets

In Part 1 of this article series described the options for integrating WebSphere Portal with IBM Business Process Manager products, and how to select the best approach for your integration project. Part 2 introduces techniques that enable bidirectional interaction between both user interfaces, and that can be layered on top of the existing components. Using this approach, the resulting solution appears as a single, seamless application.

Share:

Wolfram Richter, Certified IT Specialist, IBM

Wolfram Richter photoWolfram Richter is a consultant with the IBM Software Services for WebSphere organization. He has a 9-year history in IBM middleware and BPM technology, and specializes in integrating SAP solutions with IBM software. Before his current assignment, he worked as a pre-sales IT specialist and in education and training. Wolfram lives and works in Germany. In his spare time, he likes to spend time with his family, go jogging and fix things in his house. As he writes this, Wolfram realizes that there can never be enough spare time.



Sandro Schwedler, Certified IT Specialist, IBM

Photo of author, Sandro SchwedlerSandro Schwedler works as an Certified IT Specialist for IBM Software Collaboration Services. His areas of expertise include middleware, XML, Portlet, and Java Enterprise Edition (JEE) development. He holds a degree in Information Technology from the Berufsakademie Stuttgart, Germany.


developerWorks Contributing author
        level

15 February 2012

Introduction

A great advantage of using WebSphere Portal as the user interface to business processes is its ability to render additional portlets on the same page as the portlets showing the business process data. These "supporting portlets" typically provide functionality that is useful within and outside the business process context, such as address book lookups, content display, or social and collaborative functions. IBM Business Process Manager provides its own technology for user interfaces, called Coaches. These Coaches can be integrated into WebSphere Portal using iframes - that is, through a widget or a portlet. The Business Process Manager V7.5 Business Space widgets and the Coach portlet from the Unified Task List (UTL) package use this approach. However, simply rendering these supporting portlets side by side with the portlet containing the Coach is sometimes not enough: the Coach and supporting portlets may need to be able to exchange data. Otherwise, the end user would have to retype the data, which is unnecessarily complicated and error prone.

This article describes an approach to enabling data to flow seamlessly between portlets and Business Process Manager Coaches. Although the focus is on portlet technology, the base principles are also applicable to widgets and other web applications. WebSphere Portal 8 Beta 2 contains a version of the UTL that supports Business Process Manager V7.5. Previous versions of the UTL are available in the IBM Lotus and WebSphere Portal Business Solutions Catalog for older Portal versions that support WebSphere Lombardi Edition 7.x. The concepts presented in this article are independent of the product versions, but we'll refer to the latest versions, such as Business Process Manager V7.5 or Web Experience Factory, throughout the article.

The business scenario

In this article, we will extend the "HR Open New Position" process from the quick-start tutorial that is part of each WebSphere Lombardi Edition and Business Process Manager V7.5 installation. In this process, a hiring manager can submit a request for a new hire. If a new position is to be opened (as opposed to an existing vacant position to be filled) the request is routed to the General Manager for approval. Once approved, the request is sent to HR, which will find applicants.

Even in this simple scenario, WebSphere Portal adds value. For the initial request submission, the hiring manager could be selected from a corporate directory portlet instead of manually entering the name. This requires data to travel from a portlet to a Coach. For the approval step, a portlet could display additional information based on the Coach contents, such as a map that displays the working location. This requires data to travel from the Coach to a portlet. In addition, a portlet action, such as refreshing the task list, might be triggered once a human service has been completed. This requires the completion event to be detected.

The technical scenario

WebSphere Portal provides a mechanism for widgets and portlets to interact with each other. Once the Coach data is available in a widget or portlet, it can be sent to other widgets and portlets on the same page or on other pages. However, it is not possible to pass data from the Coach (which is rendered by the Business Process Manager server) to its containing portlet or widget (rendered by the WebSphere Portal server) or back using this mechanism. There is no server-side channel to pass this information from Business Process Manager to WebSphere Portal. As an alternative, we will describe how to pass data between Business Process Manager Coaches and supporting portlets using client-side technology. From there, server-side interactions can be triggered, if necessary.

The ability to manipulate "foreign" content in an HTML page is an easily exploitable security hole: Imagine a hostile HTML page embedding your online banking web site in a frame, with the ability to change the target account and amount of any transaction entered. This is why the browser's Same Origin Policy (SOP) allows an interaction across frame boundaries only if both the embedding page and the embedded page's URL match to a certain extent. The server must have the same DNS name (or at least the same domain) and the same TCP port number. Care has to be taken to set up the environment in such a way that the SOP will not hinder communication between the Coaches and the enclosing HTML page. Then, you can use JavaScript technology to manipulate the Coach and the portlet content. Of course, this client-side integration will work only if the Coach is visible (and not hidden on a different portal page).

Solution outline

The overall solution for this business scenario consists of many pieces, such as a WebSphere Portal and Business Process Manager setup, a single sign-on configuration, human service invocation and components to start processes and to manage tasks using a task list, and so on. In this article, we will provide exemplary solutions for four parts that are unique to Coach-portlet interaction:

  • An infrastructure setup which works around the browser SOP.
  • The development of a portlet which can send data to a Coach (for the initial request submission scenario).
  • The development of a portlet which can receive data from a Coach.
  • The ability to detect the completion of a human service.

There are various approaches to making Business Process Manager and WebSphere Portal accessible via the same host name, such as using the WebSphere Portal AJAX proxy to serve the Business Process Manager content through a WebSphere Portal URL, or using the IBM HTTP Server plugin, which can be configured to make both WebSphere Portal and Business Process Manager accessible through the same base URL. The AJAX proxy approach allows for a higher degree of flexibility in the operational model because the Business Process Manager server does not need to be exposed to the clients. After the initial configuration, this requires less maintenance than the second approach. It does, however, put a higher load on the WebSphere Portal server.

For the Portlet-to-Coach scenario, we need to put together solutions to various small problems. Assume a portlet has data available on its server-side, for example, through user input or inter-portlet communication. We need to transfer that data from the portal server-side to the browser client-side. No matter what the UI technology in question, widget or portlet, the Coach is embedded using an iframe. Given the complete HTML page, we need to identify the iframe that hosts the Coach. Once we have its ID, we can use the DOM API to manipulate the Coach's content, for example, setting the value of a field, or even to advance the human service by submitting the Coach programmatically.

Figure 1 gives an overview of this scenario. Portlets are server-side components, whenever they create JavaScript™ code to be executed in the browser, they are split into a <client-side> and a <server-side> component in these component sequence diagrams.

Figure 1. Sequence diagram of the portlet-to-Coach interaction
Sequence diagram of the portlet-to-Coach interaction

In the other direction, Coach-to-portlet, we have a similar but different set of small problems to solve. We need to provide a JavaScript function on the embedding page that can receive data from the Coach. Then, we need to invoke this JavaScript function from the Coach within the iframe. Once the data is available in the portal content on the client-side, we need to send it over to the server-side portal backend without causing a screen refresh (otherwise any unsubmitted edits will be lost). From there, it can be processed, that is, rendered or sent to other portlets. Figure 2 illustrates this scenario.

Figure 2. Sequence diagram of the Coach-to-portlet interaction
Sequence diagram of the Coach-to-portlet interaction

(See a larger version of Figure 2.)

To detect the completion of a human service, we will use heuristics. We will manipulate the iframe HTML tag to add an event handler. This event handler will evaluate the Coach's HTML whenever the iframe content is reloaded. Once the typical signature of a completed human service is detected, we can trigger various actions, such as refreshing the task list, clearing the iframe content, and so on. Figure 3 shows a simplified overview of this scenario.

Figure 3. Sequence diagram showing how finished human services are detected
Sequence diagram showing how finished human services are detected

(See a larger version of Figure 3.)

In building these solutions, we have tried to ensure that existing portal content does not need to be modified and that the setup is modular. The functionality to send to or receive data or to detect events from a Coach needs to be embedded in portlets to use the portlet interaction functions, but it does not have to be the portlet that provides the iframe. As long as these portlets are displayed on the same HTML page, the interaction will work. We can therefore create scenario-specific portlets and place them on scenario-specific pages or page templates for the WebSphere Portal dynamic UI. Existing assets, such as the UTL Coach integration portlet, do not need to be modified. These custom enhancements can be enabled for testing, which should help when requiring product support.

Infrastructure setup

Setting up the AJAX proxy to serve Business Process Manager content will be described in detail in a future developerWorks article on Business Process Manager widget integration in WebSphere Portal and is also documented in the WebSphere Portal Information Center. In this article, we will focus on the second approach, which is not recommended for a production environment because it adds an additional step - merging the plugin configuration - to the application deployment process. Compared to the setup of the AJAX proxy, however, it is simpler and yields faster results, suitable for a proof-of-concept environment.

Hiding WebSphere Portal and Business Process Manager behind the same HTTP server

The IBM HTTP Server plugin is configured using an XML file describing the backend server locations and the URL paths for which each server (cluster) is responsible. This file is typically named plugin-cfg.xml and is located in the <HTTP_SERVER_INSTALL_DIR>/plugins/<WEB_SERVER_NAME>/configuration directory. Its content can be automatically re-created based on the server or cluster configuration. This configuration is either triggered manually from the administrative console, or automatically (for example, when an application is deployed that is assigned to the web server). It is rather straightforward to manually merge the configuration created for the portal server with the configuration created for Business Process Manager V7.5. The necessary steps are described in TechNote swg21139573.

Figure 4. Overview of WebSphere Portal and Business Process Manager setup behind a common HTTP server
Overview of WebSphere Portal and Business Process Manager Setup behind a common HTTP Server

In Figure 5, you can see a setup in which the name and location of the web server plugin config file is deliberately configured differently on the WebSphere Portal and the Business Process Manager server. A merged version of the plugin has been manually created and copied to the location configured in the HTTP server's configuration. Note that this merging has to be performed every time one of the source plugin's configuration changes, for example, after deploying new applications to portal.

Figure 5. Web server configurations in WebSphere Portal and Business Process Manager
Web server configurations in WebSphere Portal and Business Process Manager

Now both portal (context root /wps) and Coaches (context root /teamworks) are available from the same HTTP server. From the browser's point of view, both come from the same origin. JavaScript in the Coach may now interact with the DOM or JavaScript of the portlet or widget and vice versa.

In addition, we need to configure the Business Process Manager application server to accept Portal's JSESSIONID cookie value as its own, establishing a new session when the one referenced in the cookie does not exist. This is done through a custom property called HttpSessionIdReuse in the web container's session management, as shown in Figure 6. Otherwise loading a Coach will cause the portal's session cookie to be overwritten, since the base URL is the same. This would cause all sorts of unexpected behavior.

Figure 6. Web container configuration for Business Process Manager with the HttpSessionIdReuse property
Web container configuration for Business Process Manager with the HttpSessionIdReuse property

Additional setup tasks

In order for the integration scenario to work correctly, additional setup tasks are necessary which are not detailed here, such as setting up a common user repository for WebSphere Portal and Business Process Manager, enabling web single sign-on, and enabling client-side aggregation in the portal pages (to allow partial screen refreshes). For more information on these topics, refer to the Resources section.

Portlet-to-Coach (initial request submission scenario)

Partial page refresh

We need to ensure that the iframe and its contents are completely rendered before the code referencing them is executed. This is why no full page refresh should take place; when the interaction is triggered, only the portlet containing the Coach integration logic is refreshed. Hence, the portlet containing the iframe and the Coach itself are already fully loaded and the JavaScript code rendered as part of the Coach integration portlet refresh can directly interact with the Coach DOM.

In a full page refresh scenario, the Coach may be loaded only after the JavaScript code has been executed, causing the interaction to fail. Working around this may include placing the Coach integration portlet after the iframe portlet on the page and registering an onLoad handler on the iframe as shown in the section on detecting finished human services. This handler would then execute the interaction code once the Coach is loaded.

In this scenario, we want to manipulate the Coach form data from other portlets, which requires the following steps:

  • Triggering the execution of a client-side JavaScript method from the server-side portlet backend.
  • Identifying the iframe that hosts the Coach.
  • Manipulating the Coach content to display the data.

Figure 1 gives a simplified overview of this interaction scenario. To trigger Coach manipulation from the server side, we will generate a JavaScript snippet, which is sent to the browser and executed on the client side after a portlet refresh. For instance, this script generation could run after an inter-portlet communication. This JavaScript snippet contains the data to be transferred to the Coach, as well as the logic to manipulate the Coach. Please note that because the Coach is running in an iframe, we have to use a partial page refresh to preserve the state of the Coach. This means that only the changed sections of the portal page are refreshed, instead of reloading the whole page. The whole page would also include the Coach form, which would then be reset to its defaults.

For portlets that do not provide their own partial reload implementation, client-side aggregation is necessary. For Web Experience Factory portlets, we can select the Refresh specified page location option in the Post-Action Behavior section of all user interface builders to avoid a full portal page refresh, as shown in Figure 7.

Figure 7. Web Experience Factory builder configured to refresh only a specified page location
Web Experience Factory builder configured to refresh refresh only a specified page location

This approach is unecessary when the event that triggers the manipulation of the Coach already happens on the client-side, for example, based on a user interaction. In that case, we can manipulate the Coach content without any server-side involvement. The sample code contains a portlet with a Dojo tree component that triggers the data transfer whenever a tree node is selected.

Identifying the Coach iframe

If you know the iframe's name attribute, you can simply use the getElementsByName() method call to retrieve a reference to it. This DOM API call returns an array of matching elements. The following code retrieves a reference to the first (and usually only) occurrence of the iframe from the UTL Coach portlet on the page:

var iframe = document.getElementsByName('lombardicoach')[0];

For a more generic approach, you could use the getElementsByTagName() method, shown below, to sift through all iframes on the page and identify the one that contains the Coach. This can be achieved by identifying a specific Coach form contained in the iframe, or by simply checking whether the source URL points to the teamworks servlet.

Listing 1. Retrieving the element id for an iframe in a generic fashion
var iframe = null;
var iframes = document.getElementsByTagName('iframe');
for (var i = 0; i <  iframes.length; i++) {
    var iframeSrcURL = iframes[i].getAttribute('src');
	
    //TODO: Adapt the URL to match your environment
    //better: use a variable to contain the base URL
    //which can be adapted to the environment during deployment
    if (iframeSrcURL.indexOf('https://server.name/teamworks/') == 0) {
        iframe = iframes[i];
        break;
    }
}

Manipulating the Coach content

Once you have identified the iframe, modifying the Coach contents is rather straightforward. In the Coach editor of the Process Designer, you can see the input element's Control Id, or HTML element Id, as shown in Figure 8. In this example, the Id is InputText2.

Figure 8. Finding the control Id in the BPM Process Designer coach designer
Finding the Control Id in the Coach designer

Changing the input field's value is now a matter of retrieving a reference to it using getElementById() and changing its value attribute as follows:

Listing 2. JavaScript function to change a value in a Coach
function changeHiringManager(managerName) {
    // code to acquire iframe reference has been removed for brevity
    var doc = iframe.contentWindow.document;
    doc.getElementById('InputText2').value = managerName;
}

Similarly, progressing a Coach can be done by identifying a button's HTML id and then invoking the click() method on it.

Putting it all together in a portlet

The sample portlet uses a straightforward implementation using the Web Experience Framework, as shown in Figure 9, but any other JSR 286 supported framework can be used.

Figure 9. Web Experience Factory model for a complete portlet-to-Coach interaction portlet
Web Experience Factory model for a complete portlet-to-Coach interaction portlet

Builder calls 4 through 8 above implement a simple form to enter some data. The button builder call refreshes the form page location after execution. Builder call 10 inserts the changeHiringManager JavaScript function in the header of the portlet page. Builder call 11 inserts the dynamic JavaScript snippet, which is executed when the portlet is refreshed, as shown in Figure 10. In this example, it modifies the string that is passed by prepending "Hello" to make it more obvious that the interaction took place through this function.

Figure 10. Web Experience Factory Client JavaScript builder which sends the JavaScript snippet to the browser
Web Experience Factory Client JavaScript builder which sends the JavaScript Snippet to the browser

Coach-to-portlet (additional information scenario)

In this scenario, we want to trigger a change in another portlet based on a user action within a Coach. For this to appear seamless to the end user, the following must occur:

  • The Coach must be adapted to send out data to a portlet via JavaScript.
  • A portlet on the same page must provide a JavaScript function to be called by the Coach.
  • The JavaScript function has to send the data to the server-side backend (which then might trigger an update in another portlet).

Figure 2 gives a simplified overview of the interaction scenario.

Invoking a JavaScript function on the embedding page from within the Coach

Decoupling BPM from Portal

The approach presented in this section has some drawbacks: the BPM content needs to be adapted in order to interact with the portal environment and care has to be taken to ensure it runs without errors outside of it.

Another approach is to inject the event handler into the Coach only when it is running embedded in the portal. The basic technique is described in the section on detecting the completion of a human service.

However, this scenario adds another level of complexity: since a human service can consist of multiple Coaches (HTML pages), the injection can take place only when the proper page is displayed. This means that first an onLoad handler would need to be injected into the iframe. It would then have to recognize the currently displayed Coach and, in turn, would have to inject the onClick handler into the HTML element.

This interaction should occur when the user clicks on the location field in the Coach, in other words, it will be triggered from an onClick event handler. Such an event handler can easily be added using Process Designer. The HTML element's id ('InputText8' in this example) can be retrieved as shown in the previous section. Create a new event of the type onClick in the Events section of the Properties tab, shown in Figure 11, and enter the JavaScript snippet below.

The snippet below first accesses the embedding page (window.parent) and then calls a JavaScript function receiveFromCoach() in the embedding page with the textContent of the Location element (document.getElementById(the Control Id of the tag)) as a parameter. Note that the document object references the document of the embedded Coach, not the embedding page, since the JavaScript code is part of the Coach. The JavaScript function does not exist yet, but will be created in the next step.

window.parent.receiveFromCoach(document.getElementById('InputText8').textContent)
Figure 11. Coach designer with configured event handler
Coach designer with configured event handler

Providing a JavaScript function to call

The next step is to create a portlet that will provide the receiveFromCoach JavaScript function. Using Web Experience Factory, create a new "Main and Page" model and add a Portlet Adapter builder. You can remove all content from the created page, since this portlet should not have any visible content; it will only provide a JavaScript entry-point for the Coach, as shown in Figure 12.

Figure 12. Basic Web Experience Factory project – page builder
Basic Web Experience Factory project – page builder

Next, add a Client JavaScript builder that will provide the actual JavaScript function for the Coach to call. The JavaScript is found in the <HEAD> tag of page1, and the code is specified directly as builder input. The function in the following listing simply pops up a message box with the value sent by the Coach.

Listing 3. Simple JavaScript function to be called from the Coach
function receiveFromCoach(aString) {
    alert(aString);
}
Figure 13. Basic Web Experience Factory project – Client JavaScript builder
Basic Web Experience Factory project – Client JavaScript builder

After publishing the project to Portal, making the web application accessible to all logged on users, and adding the portlet to the same portal page that contains the UTL Coach portlet, you can see it in action, a shown in Figure 14.

Figure 14. Coach and portlet interacting
Coach and portlet interacting

Sending the received data from the client side to the server side

You can now enhance the JavaScript function from the previous section to submit the data and trigger server-side actions. For example, you could trigger inter-portlet communication to forward the location information to a third portlet. Or you can use this information as input for a database search request. Again you can implement this approach using any framework, such as JavaServer Faces, but our example uses Web Experience Factory, as shown in Figure 15.

Figure 15. Web Experience Factory model for a complete Coach-to-portlet interaction portlet
Web Experience Factory model for a complete Coach-to-portlet interaction portlet

The builder calls 4 through 8 implement a form with one data field. This field and all other HTML elements can be hidden from the end user using CSS techniques – combined with an empty skin this portlet would be invisible. The Unique Client-Side ID builder call (8) creates an id for a client-side DOM object, in this case an input field of a form. This id is guaranteed to be unique, even if multiple instances of the portlet are rendered on the same page. This id can also be retrieved on the server-side, allowing a JavaScript method to be constructed on the server which accesses this client-side DOM object. An example is builder call 10, containing the JavaScript function shown below to be called from the Coach:

Listing 4. Programmatically triggering a submission to the backend server
function receiveFromCoach(aString) {
    var	dataInput = document.getElementById("${MethodCall/dataInput}");
    dataInput.value = aString;
    dataInput.onchange();
}

In this function, you insert the data sent from the Coach into the input field of the portlet and trigger its onChange event programmatically. To receive this event, you use an HTML Event Action builder (builder call 11 in Figure 15).

Figure 16. HTML Event Action builder to submit the form whenever the input field contents change
HTML Event Action builder to submit the form whenever the input field contents change

This builder call adds a JavaScript handler for the onChange event that submits the form and triggers the submit_al Action List builder. This Action List uses the method created by the Cooperative Source (builder 2) to send the form data to other portlets via inter-portlet communication. Please note that, in this example, we selected "Always reload the top-most page after running action" as Post-Action Behavior because a full screen refresh is required for server-side inter-portlet communication. However, this also causes the iframe to be reloaded, which means that, though the same Coach is displayed after the refresh, any data that has been entered in the Coach but not yet submitted is lost.


Detecting the completion of a human service

Refer to Figure 3 for a simplified overview of this interaction scenario.

Identifying a completed human service

Whenever a human service is completed, a specific HTML page is rendered by the Business Process Manager process server instead of a Coach, as shown in Figure 17.

Figure 17. The "the service has finished" page indicating a completed human service
The

This HTML page contains some JavaScript code that causes the Frame displaying the Coaches to be closed or cleared in a Business Process Manager process portal (or Business Space widgets) environment. Unfortunately, this does not work in a WebSphere Portal environment, which provides us with the opportunity to detect and broadcast this event to any portlet that might be interested. Looking at the HTML code for that page, shown in Figure 18, you can see that it has a very simple structure. Its body contains only a paragraph (<p>) and a <script> tag. The script is responsible for closing the process portal frame and the paragraph contains a bold (<b>) statement that states to the end user that the service has finished. The text itself is dependent on the end user's language and therefore an unreliable indicator. However this HTML structure is quite different from the rather complex HTML of the regular Coaches. This is why we can use the presence of this structure as an indicator that the service has finished.

Figure 18. Page structure of the "the service has finished" page
Page structure of the

In this sample, we use a simple JavaScript-based approach to parse the body of the content to ensure a broad browser compatibility. A more elegant approach might be realized using XPath. The JavaScript function shown below takes two arguments: a reference to the iframe displaying the human service and a function to call whenever the end of the human service is detected:

Listing 5. JavaScript function to detect a finished human service
function detectHumanServiceHasFinished(iframe, callback) {
    //get the embedded document's body
    var body = iframe.contentWindow.document.body;

    var p = null;
    var hasScript = false;
    var hasOtherTag = false; 
    
    //iterate over all child nodes of the body node
    for (var i=0; i<body.childNodes.length; i++) {
        var node = body.childNodes[i];
        
        //we're only interested in element nodes
        if (node.nodeType == 1) { 
            if (p == null && node.nodeName.toUpperCase() == 'P') {
                //if this is the first <p> tag, store its reference
                p = node;
            } else if (p != null && !hasScript 
                                 && node.nodeName.toUpperCase() == 'SCRIPT') {
                //if this is the first script tag, set a flag
                hasScript = true;
            } else {
                //in any other case (second p or script tag, other tags, ...), set a flag
                hasOtherTag = true;
            }
        }
    }

    //if the body contents themselves seem legit,
    //let's look at the content of the paragraph
    if (p != null && hasScript && ! hasOtherTag) {
        var b = null;
        for (var i=0; i<p.childNodes.length; i++) {
            var node = p.childNodes[i];

            //once again, we're only interested in element nodes
            if (node.nodeType == 1) {
                if (b == null && node.nodeName.toUpperCase() == 'B') {
                //if this is the first occurrence of <b>
                    b = node;
                } else {
                    hasOtherTag = true;
                }
            }
        }

        //if both the body and the p tag have the right contents,
        //invoke the provided callback function 
        if (b != null && ! hasOtherTag) {
            callback(iframe);
        }
    }
      
    return true;
}

The JavaScript callback function can now perform various functions, such as sending the event to other portlets (for example, to tell the UTL to refresh itself) using the frontend-backend interaction mechanisms shown before. For that you can follow the same approach described in Sending the received data from the client side to server side. The example below simply clears the iframe and pops up an alert.

Listing 6. Sample JavaScript function that is called when a completed Coach is detected
function humanServiceHasFinished(iframe) {
    //setting the iframe src attribute does not survive a full page refresh
    //but is enough to prove the concept
    iframe.src = 'about:blank';
    alert(„Human service has finished“);
}

Injecting the event handler into the Coach iframe

Now all that remains to be done is to install the event handler so it is invoked whenever the iframe's content changes. As shown above, you can get a reference to the iframe, usually using the getElementByName or getElementByTagName functions. Then it's just a matter of setting the onLoad attribute of the <iframe> tag, as shown below.

Listing 7. Injecting the onLoad event handler
iframe.setAttribute('onLoad', 
                    'detectHumanServiceHasFinished(this, humanServiceHasFinished)');

Setting this attribute needs to happen after the iframe has been loaded. Therefore, you need to ensure that the injecting portlet is placed behind the embedding portlet on the portal page. All JavaScript functions required for this scenario can be placed in a single Client JavaScript builder, as shown in Figure 19.

Figure 19. Web Experience Factory Client JavaScript builder to inject the onLoad event handler
Web Experience Factory Client JavaScript builder to inject the onLoad event handler

Importing the sample code package

The package provided for download with this article is a Web Experience Factory archive containing the portlets described in this article. The package was developed and tested using a compatible set of product versions available at the time of writing of this article: Unified Task List 4.0, WebSphere Lombardi Edition V7.2 and WebSphere Portal V7.0. To import the package, create a new Web Experience Factory project. Then right-click on the new project and select Import => Web Experience Factory Archive. Select the archive and click Import.

The package contains the following files, as shown in Figure 20:

  • OrgChart and CoachManipulator are portlets to manipulate Coach form data from outside. OrgChart uses a pure client-side approach for that. CoachManipulator does an additional server round trip for additional server-side processing.
  • CoachHelper is a portlet to detect completion of a human service.
  • The MapSupporting portlet displays a Google™ map for a location received by inter-portlet communication.
  • MapEventSender receives the location string via JavaScript eventing from the Coach and transfers it via inter-portlet communication to the MapSupporting portlet.
Figure 20. The sample package contains five portlet models
The sample package contains five portlet models

Prerequisites for running the sample are a task list and a Coach integration portlet. You can program these using the REST API or deploy them using the Unified Task List (see Resources). You can set up the sample on a single page, in which case, you need to create a new page, place all portlets on that page and wire the portlets for server-side interaction. Note that this implementation of these portlets requires server-side aggregation, so you must set this property in Page Properties. If you use the Unified Task List and Lombardi Coach portlets from the UTL package, create a wire between them to transfer the selected task id. A wire from the Map Event Sender portlet to the Map portlet sends the location string, as shown in Figure 21. To refresh the Unified Task List, a wire between the CoachHelper and Unified Task List portlets forwards the Coach completion detection.

Figure 21. The wires created for server-side portlet communication
The wires created for server-side portlet communication

Furthermore, the following client-side events occur:

  • OrgChart and CoachManipulator portlets manipulate the Hiring Manager form field of the Create Job Requisition Coach.
  • The Coach portlet sends the selected location string to the MapEventSender portlet (see Figure 22).
  • The Coach portlet sends the Coach completion information to the CoachHelper portlet.
Figure 22. The MapSupporting portlet displays a map for the selected location
The MapSupporting portlet displays a map for the selected location

Conclusion

Using client-side integration technologies, you can achieve a seamless user experience comprising both portlets and Business Process Manager Coach UIs. It is possible to send data from a Coach to a portlet, to receive data into the Coach from a portlet, and to detect the completion of a human service to trigger additional actions. Thanks to client-side aggregation techniques, data intended for or received from a Coach can be processed on the portal backend without breaking the seamless UI experience. The whole approach is modular – existing product code or portal assets do not need to be modified as new integration scenarios can be wrapped into additional portlets and deployed on top of the existing scenarios. This makes the integration approach feasible even in large projects.


Acknowledgements

We would like to thank Hauke Juhls, Kip Harris and Stefan Liesche for reviewing this article.


Download

DescriptionNameSize
Web Experience Factory Sample Projectibpmportlets.zip102KB

Resources

Learn

Get products and technologies

Comments

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


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere, Business process management
ArticleID=793015
ArticleTitle=Realizing the value of IBM Business Process Manager in the WebSphere Portal environment, Part 2: The interaction between Coaches and portlets or widgets
publish-date=02152012