Process-based UI Mashups - External Web Applications

• Background
• User Interface Use Cases
• Mashup Technology
• Using External Web Applications in Process Models

Background

While Stardust (Stardust) supports the integration of Web-based UIs for business process management activities into its Stardust Portal, this support is traditionally focused on Java based Web technologies like JSP or JSF. The introduction of process-driven UI mashups is based on several assumptions:

• The Stardust Portal and the integrated Web user interface (UI) share one HTTP session.
• The Stardust Portal and the integrated Web UI are deployed in co-location, which enables Stardust to manipulate implementation artifacts like model classes.

Web UI integration is introduced by Stardust to offer:

• First class support for non-Java based Web UIs
• Support for non-colocated deployment of Stardust and integrated Web UIs

First class support for non-Java (or rather non-JVM) based Web UIs

Web UI development proves to be a quickly changing environment offering a rapidly changing variety of tools. Most of those tools are script-based. Thus the productivity of Web developers can be increased by using non-Java (or rather non-JVM) based Web user interfaces.

Support for non-colocated deployment of Stardust and integrated Web UIs

The support for non-colocated deployment of Stardust and integrated Web user interfaces, provides the following advantages:

• Due to the current state of Java modularity there are several limitations in how one can mix and match Java libraries inside the same deployment unit. Being able to package Stardust and the Web user interface to be integrated into separate deployment units allows both, managing dependencies separately thus giving freedom to the project, while still providing good portability for Stardust itself.
• Being able to deploy Stardust-based process and corresponding Web user interfaces separately, gives additional freedom to manage the lifecycle of both more independently, for example to update the visual aspect of user interfaces more frequently, but still expose a stable and well-defined interface towards Stardust.

User Interface Use Cases

Embedding a GWT Web Application

Being browser-based, there is no server side session that could be used to share state between Stardust and the GWT (Google Web Toolkit) application.

Thus, Stardust provides specific APIs, which are described in the section JavaScript API and SOAP Web Service API respectively. A GWT application might be integrated as follows:

• When invoking the GWT application, Stardust appends the following query parameter to the URI:

  ippInteractionUri=http://...

• In its onModuleLoad() method, the GWT application extracts the Interaction URI via the following code:

  Location.getParameter("ippInteractionUri")

  and stores it as a field for example.
• Using this URI, the application uses the HTTP GET method one or several requests to retrieve input parameters for the application
  • assuming the input parameters consist of just primitive or structured data, the recommended technique is requesting a JSON representation of the parameters.
  • using overlay classes the application will be able to work with the values returned without any additional parsing being required, just casting the JSON response to the expected overlay type.
• The form will display the retrieved values as required, provide additional information and means to input or edit data.
• Once the user indicates editing is done, the application uses HTTP PUT requests to write output values into the Interaction Resource.
• After successfully writing all output parameters, the application uses a JSNI (JavaScript Native Interface) callout to trigger a close operation on the embedding iframe.

For detailed information on the usage of GWT applications, please refer to the Google Web Toolkit documentation site.

Mashup Technology

• Provided Techniques by Stardust
• Concepts
• Message Exchange
• SOAP Web Service API
• JavaScript API
• Termination of the current interaction
• Using Session Based Web Applications

Provided Techniques by Stardust

Stardust provides techniques for lightweight and implementation technology neutral Web mashups as follows:

• using HTML iframe to embed self-contained, externally generated Web pages into the Stardust Portal user interface.
• using HTTP based REST (Representational State Transfer) for data exchange between Stardust and Web UIs.
• alternatively using a SOAP Web Service for data exchange between Stardust and Web UIs.
• a clean and simple JavaScript API for passing messages from the Web user interface to the embedding Stardust Portal.

Concepts

Interaction Resource

To enable REST based interaction with an interactive activity instance, Stardust provides the concept of an Interaction Resource. This resource provides means to perform the following interactions according to REST principles:

• Inspect the definition of the associated activity instance by retrieving:
  • general information about the activity like its name and description, as stated in the process model
  • the list of input parameters for the activity including name and data type
  • the list of output parameters for the activity including name and data type
• Inspect information about the owner of the interaction (the current user performer of the activity instance) like name, user ID and associated Stardust partition.
• Retrieve the value of input parameters (either in batch for all parameters or for just one parameter).
• Write values for output parameters (either in batch for all parameters or for just one single parameter).
• Set the current interaction status to be able to control the set of valid state transitions for the associated activity instance.

An HTTP binding of the WADL endpoint is typically be provided at

${ippServicesBaseUri}/rest/application.wadl

Find an example WADL (Web Application Description Language) description at the Web Application Description Language site of W3C.

Interaction Lifecycle

The lifecycle of any interaction resource is associated with the duration of the associated activity instance in state Application.

• An Interaction resource comes into life as soon as the associated activity instance is activated inside the Stardust Portal.
• As soon as the associated activity instance transitions into another state (i.e. gets suspended) or is passed to a different user (the owner of the Interaction changes), an associated Interaction resource will cease to exist.
• External code can manipulate the Interaction resource freely during its lifespan.

No manipulation to the Interaction resource will immediately cause a state change on the associated activity instance. Such state change will only occur under orchestration from the embedding Stardust Portal.

Supported Media Types for input and output parameters

Depending on the data type being used for input and output parameters for interactions, various media types can be produced and consumed. The following list describes the primary media type per data type and possible alternative representations:

• primitive data:
  • are natively represented as text/plain.
  • alternatively an application/ JSON representation can be provided.
• structured data:
  • are natively represented as application/xml
  • alternatively an application/JSON representation can be provided although some limitations remain (i.e. as XML namespaces are dropped from element and attribute names i.e XML containing sub elements with identical local names but different namespaces cannot be mapped to a JSON representation without loss of data).

Batch read / write

As batch operations need to encode multiple parameters in one data structure, there is no means of providing the same kind of flexibility in media type support as with single parameter read / writes. The representation for batch reads and writes is application/xml. The values for parameters are included in the XML message in their primary representation.

Message Exchange

The following sequence diagram depicts the message flow between all participants:

Figure: Sequence Diagram describing Message Flow

SOAP Web Service API

An additional SOAP API equivalent to the previously described REST API is provided. The mapping between SOAP operations and REST requests is as follows:

• getDefinition maps to GET <<interactionUri>>/definition
• getOwner maps to GET <<interactionUri>>/owner
• getInputParameters maps to GET <<interactionUri>>/inParams
• setOutputParameters maps to PUT <<interactionUri>>/outParams

Binding to a SOAP Endpoint

An HTTP binding of the SOAP endpoint is typically be provided at

$\{ippServicesBaseUri\}/soap/BpmInteractionsService

A WSDL contract can be obtained from

${ippServicesBaseUri\}/soap/BpmInteractionsService?wsdl

To simplify Web UI development, the base location of the calling Stardust Portal services endpoints is provided by an additional query parameter named ippServicesBaseUri, for example:

ippServicesBaseUri=http://localhost:9090/dev/services

This query parameter can be used to transparently bind to a SOAP endpoint implementation of the invoking Stardust Portal.

JavaScript API

Embedded Web UIs are provided with a JavaScript API supporting in-browser interactions with the embedding Stardust Portal. The API is provided in form of a JavaScript source file, which you find in the folder META-INF/xhtml/processportal of the ipp-workflow-perspective.jar, residing in the ipp-portal.war.

This file needs to be included as follows:

<script type="text/javascript" src="${ippPortalBaseUri}/plugins/processportal/IppProcessPortalClient.js"></script>

If this path is not accessible, then copy the IppProcessPortalClient.js from the ipp-workflow-perspective.jar file and specify the location of the copied file.

After inclusion, a new module InfinityBpm.ProcessPortal will be available. Any of the following operations is exposed as a function defined in the InfinityBpm.ProcessPortal module.

The InfinityBpm.ProcessPortal provides the following methods:

Example Usage

You can use such code in your custom pages, which are shown via the External Web application application type. You can leverage the activity-instance buttons of the Stardust Portal toolbar right away in your own page by the JavaScript methods mentioned above.

<html>
<head>
<script type="text/javascript" src="${ippPortalBaseUri}/plugins/processportal/IppProcessPortalClient.js"></script>
</head>
<body>
<button onclick="InfinityBpm.ProcessPortal.completeActivity()">Complete your activity instance now</button>
</body>
</html>

Query parameter ippPortalBaseUri

To simplify Web UI development, the base location of the calling Stardust Portal is provided by an additional query parameter named ippPortalBaseUri, for example:

ippPortalBaseUri=http://localhost:9090/dev

This query parameter can be used to transparently bind to a JavaScript implementation of the invoking Stardust Portal.

Termination of the current interaction

To allow embedded panel to actively terminate the current interaction and allow the user to work on different activities, the functions completeActivity, suspendActivity(boolean) and abortActivity are provided. Both functions will cause an equivalent side effect as explicitly clicking on the appropriate button in the activity panel toolbar. The following example shows how to invoke this API from a Grails submit button, triggering a Suspend and Save:

<g:submitToRemote class="save" value="Save and Close" action="ajaxPost" 
        onComplete="InfinityBpm.ProcessPortal.suspendActivity(true)>

Successful termination of a Web UI interaction will require a previous write of output parameters via either a REST operation against the Interaction Resource or an equivalent invocation of the appropriate Web Service API.

Using Session Based Web Applications

When using external panels that are session-based, launching multiple ICEfaces or Trinidad activity panels via URI query parameters can break the initialization of the embedded panels. Thus, if external panels are session based, please make sure the state management is considering the interaction ID in addition of using session scope. Please note that Trinidad and ICEfaces panels embedded sharing the portal session can be adjusted by using portalTab scope beans instead of session scope beans.

Using External Web Applications in Process Models

To add an External Web Application to a model perform the following steps:

1. In the diagrams toolbar select Int. Applications > External Web Application.
   (Alternatively, in the Outline view right-click Applications and choose New Interactive Application > External Web Application.)

   
   Figure: Create an External Web Application.

2. Open the properties dialog.
3. Expand the Interactive tree in the left pane and select External Web Application.

   
   Figure: External Web Application Properties.

4. In the right pane enter an arbitrary URL for your application.
5. Select Typed Access Points in the Interactive tree in the right pane.
6. In the Typed Access Points pane, you may define an arbitrary list of access points for your application. Supported data types are primitive (except of type char or Calendar) or structured data.
7. Note that if the Displays Imported Model Elements as Groups check box is selected, the access point list displays references for the referenced structured data. Selecting the check box also groups local and referenced elements.

Figure: Add Input Source Parameters

Figure: Setting Typed Access Points.

Modifying the Typed Access Points

You can modify the specified source and target access points.

1. In the Typed Access Points pane, right-click the root of access point and then select Modify

   
   Figure: Modify Typed Access Point

2. Specify the parameters in the Modify Parameter dialog box and click OK

   
   Figure: Modify Typed Access Point

Deleting the Typed Access Point

You can delete the source and target access points.

1. In the Typed Access Points pane, right-click the root of access point and then select Delete Parameter

   
   Figure: Delete Typed Access Point

   The Warning dialog box gets displayed.
2. Click OK to delete the access point parameter

   
   Figure: Warning - Delete Typed Access Point

Data Mappings

You can use access point path as well as data path in the data mapping. Per default, only the full value of a parameter is used. You can change this behavior to either enter the name of declared parameters or the data mapping IDs. To have both options, change the property Carnot.Compatibility.Interactions.SupportDataMappingIds, in your carnot.properties file to true.

It is also possible to write an attribute of a structured parameter to a primitive variable, e.g.:

Figure: Using a Structured Data Attribute in Out Data Mapping

Example Usage

This is a small example to demonstrate the usage of an External Web Application associated with an application activity.

In a dynamic Web project create a model as follows:

• Create the following activities in a sequence:
  1. manual trigger
  2. manual activity
  3. application activity
  4. manual activity
• Create structured data types Address and Person, e.g.:

  
  Figure: Structured Type Address
  
  
  Figure: Structured Type Person

• Add structured data of each of these types.
• Create an External Web Application.
• In the properties page enter a URL for your application, e.g. http://www.wikipedia.com.
• In the properties page Typed Access Points pane, add the structured data of type Person to as input and the structured data of type Address as output resources:

  
  Figure: Add Typed Access Points

• Add an in and out data mapping from the structured data of type Person to the first manual activity.
• Additionally create an in-data-mapping from this structured data to the External Web Application.
• Create an out data mapping from the External Web Application to the structured data of type Address.
• From both structured data create an out data mapping to the last manual activity.

Your model now looks similar to the model in the following figure:

Figure: Example Model

Testing the example

Now start your server, deploy the model and run the activity associated with the External Web Application in the Stardust Portal. Your application should come up with the URL you entered in the properties page.

For example, if you entered the URL http://www.wikipedia.com, the following page is coming up:

Figure: Example URL.

Now you may inspect the interaction via its REST interface.

Figure: Interaction URI

Selecting one of these options displays the according xml file. For example Show In Data Values displays all the in-data values of the activity, which invoked the External Web Application:

Figure: Example - Show In Data Values

entered in the entry fields for a structured data:

Figure: Example - Entered In Data Values.