Wednesday, January 18, 2012

Create interactive dashboards with InterWindow Communication (IWC)

In a previous post I mentioned a new feature of PeopleTools 8.52: Dashboard. With this feature you can create custom dashboards with pagletes that provide information about a certain business area. Oracle didn't stop here and also added Interwindow Communication (IWC).

Interwindow communication is a frame-to-frame messaging mechanism that enables browser window objects—such as pages or pagelets—to be aware of and react to field-level data changes that occur in other window objects that share the same browser window. Interwindow communication enables you to publish field-level changes as they occur so that any subscribing page or pagelet becomes instantly aware of the change and then, can act on it in real-time. Administrators, subject matter experts or application developers configure page fields to respond to either changes in value or a mouse click. When the triggering event occurs, the application posts a string-formatted message. Because of partial pagelet refresh functionality, subscribing pagelets can then respond within the context of the data contained in the message. Interwindow communication supports component-based pagelets and noncomponent-based pagelets (iScript-based or other Pagelet Wizard pagelets).

How does it work?

  1. Triggering event occurs on Pagelet A.
    User clicks a button or link or changes the value of a field that is configured to publish.

  2. IWC generates message.
    Simple string formatted message temporarily stored to IWC-related table.

  3. Pagelet B reads message.
    Listener checks to see if loaded pagelets subscribe to the message.

  4. Determine whether update action is necessary.
    Check the document object model of the pagelet and run a field change event if necessary.

  5. Determine whether refresh is necessary.
    If configured to refresh, page refreshes partially or with new parameters.
I will elaborate IWC with the following example.

Create 2 components, that will be published as pagelets. Pagelet A will have two prompt fields, SETID and DEPTID.  IWC will be configured to publish these fields when field DEPTID is changed.

Pagelet B will have fields SETID and DEPTID on level zero and on level one an grid with Employees on that department. IWC will be configured to subscribe to the publishing event of Pagelet A. Fieldchange on field DEPTID on pagelet B will flush and reselect the employees on the grid every time the field DEPTID is changed in pagelet A.

Create pagelet A

Start off by creating a page and setting the field that trigger the IWC publish to interactive  mode. Also add a Page Field Name. The Page Field Name will force the HTML name of this field to be the same as the Page Field Name, otherwise PeopleSoft will change the HTML field name to something like [PAGENAME]_[FIELD]. IWC will be configured on HTML field names, so this will help us to have the correct HTML field name.

Add the page to a component and add the component to a menu, but do not run the Register Component Wizard. We will create a content reference of type Pagelet manually. Go to Main Menu - PeopleTools - Portal - Structure and Content and add a new content reference in (sub)folder Root - Portal Objects - Pagelets.

Set Usage Type to Pagelet and set URL Type to PeopleSoft Component and enter the Menu Name and Component Name of the publishing component/pagelet.

Create pagelet B

Same a pagelet A, create a page with SETID and DEPTID on level zero and add a grid with employees. Set the field style of SETID and DEPTID to PTTRANSPARENT, this will make the fields non-visible to the end-user , but still visible to HTML.

As with the publishing pagelet, add this component to a menu and create a content reference to this component of type Pagelet.


Now you can add the pagelets to a custom dashboard. Go to Main Menu - PeopleTools - Portal - Dashboards - Manage Dashboard Pages and create a new dashboard and add the pagelets to the dashboard.

Configure IWC

To configure IWC publishing and subscription on the pagelets, we first need to know the HTML field names. We already had set the Page Field Name in Application Designer, but to be sure, we will verify the HTML field names. Best way to do this, is to have Firefox installed with Firebug extention or to have Google Chrome installed. IE doesn't show the HTML field names using View Source.

In the screen above I used Chrome and rightclicked on the field DEPTID of the publishing Pagelet and selected Inspect Element. This will bring up the HTML source code and the HTML field name of the field. Do this for all the fields, that will be used in the IWC publishing and subscribtion.

Now that we have retrieved the HTML field names, we can configure IWC.

Go to  Main Menu - PeopleTools - Portal - Inter Window Communication and add a new entry for the Portal Object Name of the publishing pagelet.

Suppy an Event Name and Message Type Pub. Set Event to Change or Click (both seem to work) and set HTML Field Name to the field with will be publising the message. Set message data to all the fields you want to publish separated by a comma.

Now create another entry  for the Portal Object Name of the subscribing pagelet.

Set Event Name to the same event name as the publishing event. Set Message Event Type to Sub and set Event Type to Partial refresh. This wil refresh only the fields that are changed, instead of refreshing the entire pagelet and will trigger the FieldChange PeopleCode event.

See it in Action

See following sneak preview of a dashboard with IWC, which I will be demoing on Oracle Open World 2012


  1. Mathew4:17 PM

    Hi Hakan,

    Thanks for the article, we managed to follow through and have our first IWC working.

    Your article mentioned that "Interwindow communication supports component-based pagelets and noncomponent-based pagelets"
    Would you be able to shed some lights on how to configure IWC to work with URL Datasouce base Pagelets? The Peoplebook 8.52 suggests the "Refresh with Parameter" as one of the possible options to use, however, this option is not visible on the IWC configuration page. At a high level, what we want to achieve is to pass a URL parameter to the pagelet using IWC. But the option could not be found as suggested in the documentation

    Any thoughts would be greatly appreciated.


  2. Krishna12:24 AM


    I have followed all your steps but still unable to make it to work. Pagelet B values are not refreshing after entering the values in first pagelet.
    Is it possible for you to provide the export project file.


  3. Hi Hakan,

    I've tried to follow your example with very similar pagelets and I'm not able to get the message to send to Pagelet B. Do you have any other notes to add that may help? I'm wondering if I must have something specific enabled or an app server setting that I may be missing. Or if possible can you send an export of your project that I can look at? Thanks.


  4. Hi John,

    I had quite some unpredictable behaviour when running on 8.52.02.
    After I upgraded the patch level to 8.52.05. it started working better.

    Try upgrading to patch level 8.52.05 and see if this helps.


  5. Jim Ogletree4:02 PM

    I too have been unable to make this work - very frustrating. For your components, are you using installation table to prevent search? Are you using any peoplecode on fieldchange or other? I would love it if you saved your project to a file and made it available.

  6. Hi Hakan,

    What are the records you used in the pagelets. Could you explain the record structure please.....

  7. David6:14 PM

    Have you been able to set up multiple partial refresh subscribing pagelets to the same publishing events? The pagelet on the left works as expected. The one on the right receives the new value, but the fieldchange code does not fire. The processing spinning image appears but never goes away.