Understand the InterviewSession

The InterviewSession is the core component of an Interview Session. It is responsible for managing the data held within the rule session, creating screens and driving interview flows. As such, it is common to interact with this object when building extensions. This following information describes some of the common things you may wish to use the interview session for.

Most importantly, from a extension perspective, the InterviewSession object contains the current data of the session interview (the Instance Data) as well as data about the interview's rulebase (the Rulebase Model Data). The InterviewSession object exists in the Interview Engine Layer.

 

The following diagram demonstrates the class hierarchy and domains:

 

 

 

The InterviewSession object has many other members  - it encapsulates session state data in the Determinations Engine layer. But for this section we will focus on its Session member and indirectly the Rulebase object (via its InterviewRulebase member) because those two objects contain the instance data and rulebase model data of the current Web Determinations Interview.

For more information on how the Interview Session, and the Interview Engine API works in general see Create a custom interview user experience.

Which Web Determinations Extensions can access the InterviewSession object

The InterviewSession object is accessible to some Plugins and Event Handlers that require access to instance data and/or rulebase model data to provide functionality.

Accessing Rulebase Model and Instance Data (via InterviewSession object)

It is important to understand the InterviewSession object as this object contains both Rulebase Model Data and Instance Data. Thus it is used by many Plugins and Event Handlers.

Definitions:

Using the Rulebase Model Data

The Rulebase Model Data is encapsulated in the Rulebase object (com.oracle.determinations.engine.Rulebase). The Rulebase object is accessible if the Web Determinations Extension has access to the SessionContext object, InterviewSession object, or InterviewRulebase object.

The basic hierarchy in the Rulebase is that the Rulebase object contains a List of Entity objects. Each Entity object contains all the Attribute and Relationship objects associated with that Entity. This hierarchy matches the hierarchy of rule authoring in Oracle Policy Modeling - each attribute and relationship is always related to an entity.

 

 

With knowledge of the above hierarchy, the most basic way to access each Entity and each Attribute and Relationship of an Entity would be via looping through each Entity, and retrieving and looping through Attributes and Relationships for each Entity. See sample code below.

 

Loop through all Entities, its Attributes, and Relationships (Java)

 

For more information about the Rulebase, Entity, Attribute, and Relationship objects, please consult its API documentation for Java or .NET.


Rulebase object: useful methods - the following is a list of Rulebase object members and also useful methods to access those members.
Note that an Entity Attribute or Entity Relationship object can be accessed directly from the Rulebase object via helper methods, to eliminate having to manually find a specific Entity to retrieve an Attribute or Relationship.

|| Member || Description
|| Access Methods
||
| Global Entity
| This is the Entity object for the Global Entity of the current rulebase
| Entity getGlobalEntity()
|

| Entities | All the Entities of the current rulebase
| List getEntities()
Entity getEntity(String name)
|
| Entity Attribute
| Retrieve a specific Attribute object of an entity
| Attribute getAttribute(String attributeName, String entityName) |

| Entity Relationship
| Retrieve a specific Relationship object of an entity
| Relationship getRelationship(String relationshipName, String entityName)
|
 

Properties Key/value pairs associated by the rulebase author to the rulebase for custom functionality
Map getProperties()
String getPropertyValue(String key)


Using the Instance Data

The Instance Data is encapsulated in the Session object (com.oracle.determinations.engine.Session). The Session object is accessible if the Web Determinations Extension has access to the SessionContext object, or the InterviewSession object.

The various Instance Data objects are as follows:

 

Accessing Instance Data is different to Rulebase Model Data - the Instance Data inside the Session is not accessible directly. The most common way to access Instance Data is to use the Rulebase Model data object (Entity, Attribute, or Relationship) and pass session data to their methods (either Session or EntityInstance). This will be explained in detail in the subsections below.

Entity Instance

There are two ways to access Entity Instance Data.

  1. Via the Entity object
  2. Via the Session object

 See the Class Diagram below for methods in the Entity and Session object that retrieve EntityInstance objects, and Sample code - Using Instance Data for actual code usage.

 


Attribute Instance

There is only one way to access Attribute Instance Data (Attribute value), and it is by using the Attribute object, passing an EntityInstance, and retrieving the value of the Attribute for the EntityInstance object passed. See the sample code below and also the section below, Sample code - Using Instance Data.

 

Accessing Attribute Instance Data

Relationship Instance (Source and Target EntityInstances)

As mentioned previously - Relationship Instance Data cannot be retrieved. Rather it is a matter of retrieving Target EntityInstance(s) by providing the Source EntityInstance - or vice versa, retrieving Source EntityInstance(s) by providing the TargetEntityInstance. See the sample code below and also the section below, Sample code - Using Instance Data.

 

Accessing Relationship Source and Target EntityInstance(s)

Sample code - Using Instance Data

Below is sample code that combines all the sample code for Entity, Attribute, and Relationship Instance Data and uses them together.

 

Sample code for using Instance Data objects (Java)

Modifying the Instance Data

As mentioned in the overview and in Using the Instance Data, Instance Data of a Web Determinations Interview lives within the Session object in the Determinations Engine Layer. Modification to the Instance Data inside the Session object is different to accessing/retrieving the Instance Data. Modification is done via transactions, and the changes to be made to the Instance Data is encapsulated inside an object.

Modifying the Instance Data inside the Session object is done indirectly via the two objects below:

 

Below are class diagrams for the RuleSessionManager and InterviewUserData objects. Only class members pertinent to modification of Instance Data is displayed.

 


The most common process for using InterviewUserData is as follows:

  1. An Interview Engine object creates an InterviewUserData
  2. The InterviewUserData is populated with content - the changes to be made; for example, additions and deletions to instance/attribute/relationship instance data, modifications to attribute value of an instance.
  3. The InterviewUserData passed by the Interview Engine object to the RuleSessionManager.setData() method.
  4. The RuleSessionManager reads the InterviewUserData and performs the changes to the Session object

 

An example of how the InterviewUserData to modify Instance Data is demonstrated by the Web Determinations Extension 'Data Adaptor' and its load() method. The load() method allows Instance Data from a datasource to be loaded into the Interview session before the user starts the Interview (see Data Adaptor Plugin).

When Web Determinations calls the Data Adaptor load() method, the load() creates, populates, and returns an InterviewUserData object that represents the Instance Data to be loaded. Web Determinations then passes the InterviewUserData object to the RuleSessionManager.setData() so the Instance Data can be loaded into the Session object (which would have no Instance Data since it's newly started).

 

Note: Because DataAdaptor load() is always performed to a newly created Session object, modifications to the Instance Data (signified by the 'Perform Modifications to Session' message) will all be 'additions' instead of additions/modifications/deletions since there is no Instance Data in the Session object to modify or delete.

For information on how to create a InterviewUserData object see Construct the InterviewUserData