Scenario Invocation: Getting Data to and from the Conductor


The Conductor is the engine behind WebCenter Personalization (WCP) that allows flow-based documents, called "Scenarios", to be managed and executed on the server-side through a well published and RESTful api. This blog post will dive more into the details of how you go about getting data into the system (as scenario input parameters), as well as getting data out of the system (return objects from scenario invocation).   A sample application demonstrates all of the topic details we'll cover.

Getting Started

 If you're not yet familiar with WCP, a good jump-start to using WCP may be found here. It includes a JDeveloper application and references to many other good documentation sites.

Otherwise, I assume you're familiar with JDeveloper and WCPS, so we'll start with a different sample JDeveloper application for this blog post.  Download the sample application, unzip it to a new folder, and open the 'CustomProviders.jws' application in JDeveloper.  This blog post will reference classes and other files that are included in that project, which provides working examples of scenario input, output, and invocation.

Passing Input Parameters to the Scenario

In the first release of WCP, scenario input data is limited to type String.   Once data is in the system, components such as data or function providers, can generate output objects -- without restriction of types -- that can be used as input to other components.  

As an example, the sample application has a scenario, 'ScenarioInput', that takes a String parameter 'userName'.  This input is specified by right-clicking on the 'Start' scenario node, then parameterizing it as follows:

Note that 'userName' is passed to the HelloWorldProvider as the ${userName} variable.

Scenario Invocation


The sample application comes with an AJAX client, 'invokeScenario.html'.  The input parameters are specified using raw XML as shown below, and the response is returned as Json, displayed as raw text in this simple dialog:

The jump-start personalization sample JDeveloper application has several other AJAX-enabled UIs created specifically for the out-of-the-box providers such as CMIS (for content), Activity Graph (for recommendations), and People Connections (for WebCenter user profile information).   Parameter input is optional, depending on the scenario.  

The AJAX client interacts purely with the Conductor REST interfaces.

Conductor Java API

Parameters may also be sent to the Conductor via a Map<String,String> parameter map.    Here is the Java code snippet taken from 'invokeWithInput.jsp', which uses the ConductorDelegate (included in the sample app) to execute the scenario.  Any number of parameters may be placed into the Map, but they must all be of type String.

ConductorDelegate client = new ConductorDelegate();
Map<String,String> params = new HashMap<String,String>();
params.put("userName", "Benji");
String message = (String)client.testScenario("HelloInput", params);
out.print("Message: " + message);

The ConductorDelegate has several more methods that let you specify the list of non-primitive, marshallable classes that will be returned from the scenario.  More will be said about this in later... For now, notice that the return for all the calls to ConductorDelegate are Objects that may be cast to some other class.

The Java API must be invoked from a web client, such as a JSP.

EL (Expression Language)

The sample application also includes 'elWithInput.jsp', which shows how to use the Java Expression Language (EL) to invoke a scenario with input parameters.   Parameters are placed in the Personalization Context, which is well-documented here.   The EL examples have two different ways of referencing the Conductor, depending on whether the Conductor URL connection has been configured.  See the JDeveloper Tutorial for creating a Personalization application for more information.  More details on using JSTL tags may be found here

Basically, parameters are sent to the scenario via EL as follows (would all be on one line):


So to send the 'userName' as an input parameter, we use (again, all on one line):

<c:out value="${p13nContext

The EL client must be invoked from a web client, such as a JSP.

Returning Objects from a Scenario

The next section will use the 'ComplexProvider' data provider as shown in the sample application.

Some Ground Rules: Marshaling Objects

As mentioned before, scenarios accept only String as input parameter objects (this will change for later releases so that any marshallable object can be used as an input parameter).   However, the scenario can return any object, as long as it is marshalable.  This requires annotating the class with JAXB.   Note that your data or function provider can return non-marshallable objects, as long as those remain in the scenario (for example, to be passed to another scenario invocation) and are not returned over the wire to the calling client.

For JAXB, the sample application has a ComplexProvider data provider that returns a custom Document object.  Check out that Document class to see the annotations.  If you're unfamiliar with JAXB, check out this link for more information.  It is also possible to generate JAXB classes directly from XML schema in JDeveloper, although I haven't tried that just yet.

Hints to the Conductor about return types

Let the Conductor know about your JAXB classes by placing this file, "conductor-client-classes" in your provider's META-INF folder.  The file's contents will contain a line entry of class names that could be returned from your provider.  Primitive Java types are not necessary to include here.  Be sure to include that in your final provider jar file.  The sample application has already done this for the ComplexProvider.

Accessing return objects via the Java API

Assuming you have already hinted to the Conductor about your Document class as a return type, you can simply invoke the Java APIs as shown in the invokeComplex.jsp snippet here:

ConductorDelegate client = new ConductorDelegate();  
Document doc = (Document)client.testScenario("ComplexDocument");
out.print("Document: " + doc);

If you encounter a situation where you return an object that has not been hinted to the Conductor, you could use an alternative API to the ConductorDelegate and hint at the class as such:

ConductorDelegate client = new ConductorDelegate();  
Document doc = (Document)client.testScenario("ComplexDocument", Document.class);
out.print("Document: " + doc);

Accessing return objects via EL

The sample application also shows how to access the return object via EL, in 'elComplex.jsp' (the first call goes all on one line).  Here, we assign the variable 'document' to the return value, and access its attributes via EL dot notation.  Note that our Document class must have public getters for us to use EL in this manner:

<c:set var="document" 

  <c:out value="${document.title}"/>
  <c:out value="${}"/>
  <c:out value="${document.price}"/>
  <c:out value="${document.published}"/>

 UIs Specific to return types

This particular UI uses jQuery to format the scenario results, which are Activity Graph Recommendations objects, into a jQuery grid.  See the sample application in the jump-start blog for the source code; it could provide a starting template for your custom return objects.


There are several different client APIs to invoke scenarios, depending on the context of the caller.  This article has provided more detail about each of those clients, and supplied working examples of using those clients.  We discussed the importance of making your return objects marshallable, and recognizable by the Conductor to send back over the wire to the caller.   Some simple uses of the Java Expression Language (EL) were introduced, including the use of dot notation to reference class attributes.


Post a Comment:
  • HTML Syntax: NOT allowed

This blog is dedicated to topics related to WebCenter Personalization, a new feature in Oracle 11gR1. It will focus mostly on a hands-on approach of how to leverage Personalization in your application to target and maintain customers by delivering dynamic, relative content.


« April 2014