Retrieve and store event payload

In a normal portal environment, most of the business portlets that participate in a single dialog contribute to a well-defined business domain model. They can therefore exchange data through a set of well-defined events. However, we might want to include portlets that are not perfectly aligned with that business model, for example third-party portlets or older portlets. We can include such portlets with the UX Screen Flow Manager.

To describe the available options, here is a simple example with a business screen flow:

A portlet portlet1 can emit the ID of an employee. It emits this ID using a JSR-286 event with the QName employeeID. A second portlet portlet2 can receive the ID of an employee, but it expects this ID to be sent through a JSR-286 event with the QName userID. Without extra translation, the two portlets cannot communicate with each other because the events they exchange use different QNames.

The UX Screen Flow Manager supports two mechanisms that enable such incompatible portlets to exchange data with each other:

• Event mappers. For more information, read Event mappers.

• The explicit specification of dialog context (DCX) keys when events are associated with referenced transition endpoints.

The dialog context (DCX) acts like the transient memory of a dialog. It maintains contextual information that is passed from one subdialog that is from a portlet, to subsequent subdialogs that are portlets. It makes information that a subdialog already provided available for all subsequent subdialogs. For more information about the dialog context (DCX), read Main components.

The DCX is divided into segments where each segment holds data or contextual information of a single dialog instance. Normally, when specified events, the QName defines how and under which key the corresponding payload is stored in the segment of the specific dialog instance. For example, after you run the transition shown in code sample 33, the DCX will contain the following. An entry with key = employeeID and a value that matches the payload sent with the corresponding event. The portlet2 is then initialized with the data stored in the DCX under the key userID. If no previous transition stored anything under the key userID, portlet2 does not receive any data.

Code sample 33:

01  <transition>
 02      <source>
 03          <transition-endpoint nameref="portlet1">
 04              <event qname="employeeID"/>
 05          </transition-endpoint>
 06      </source>
 07      <target>
 08          <transition-endpoint nameref="portlet2">
 09              <event qname="userID"/>
 10          </transition-endpoint>
 11      </target>
 12  </transition>

DCX keys make it possible to specify under which key a portlet stores data in the DCX, or under which key a portlet reads data from the DCX. To enable portlet1 to communicate with portlet2, we have the following two options:

• We can make portlet1 store its payload under the key userID, even though it emits an event with the QName employeeID. Code sample 34 shows how we can make portlet1 store data under userID.

  Code sample 34:

  01  <transition>
   02      <source>
   03          <transition-endpoint nameref="portlet1">
   04              <event qname="employeeID" dcx-key="userID"/>
   05          </transition-endpoint>
   06      </source>
   07      <target>
   08          <transition-endpoint nameref="portlet2">
   09              <event qname="userID"/>
   10          </transition-endpoint>
   11      </target>
   12  </transition>

• We can make portlet2 read the key employeeID, even though it expects an event with the QName userID. Code sample 35 shows how we can make portlet2 read data under employeeID.

  Code sample 35:

  01  <transition>
   02      <source>
   03          <transition-endpoint nameref="portlet1">
   04              <event qname="employeeID"/>
   05          </transition-endpoint>
   06      </source>
   07      <target>
   08          <transition-endpoint nameref="portlet2">
   09              <event qname="userID" dcx-key="employeeID"/>
   10          </transition-endpoint>
   11      </target>
   12  </transition>
  

The DCX segment stores data for the entire lifetime of a specific dialog instance. This action means there is no direct wiring between a source and a target. Whatever data is stored is based on what a source sends, and can be accessed by any portlet that act afterward. Code sample 36 shows how portlet1 provides data that is then used by portlet4.

Code sample 36:

01  <transition>
 02      <source>
 03          <transition-endpoint nameref="portlet1">
 04              <event qname="e1"/>
 05          </transition-endpoint>
 06      </source>
 07      <target>
 08          <transition-endpoint nameref="portlet2">
 09              <event qname="e2"/>
 10          </transition-endpoint>
 11      </target>
 12  </transition>
 13  <transition>
 14      <source>
 15          <transition-endpoint nameref="portlet3">
 16              <event qname="e3"/>
 17          </transition-endpoint>
 18      </source>
 19      <target>
 20          <transition-endpoint nameref="portlet4">
 21              <event qname="e1"/>
 22          </transition-endpoint>
 23      </target>
 24  </transition>

• Event Mappers
  In more complex scenarios, it might not suffice to adapt only the event names or QNames. Sometimes the payload itself needs to be transformed.

• Packaging of event mappers and JAXB serialization
  It is good practice to package event mappers in a shared library rather than together with the business portlets.

Parent Advanced concepts

Related concepts:

Event Mappers
Main Components