Business Flow UI Strategy

1. Overview
Starting in phase 3, the UI must access the APIs via Business Flow. A business flow engine has been
developed that takes configuration files that allow the order and number of API calls to be configurable for
each flow. This document describes the common UI code that has been developed to make use of Business
Flow and provides additional information on the overall strategy for combining classes in the web flow (via
the struts-config file) to make use of business flow.

2. Business Flow Constants

BFConstants.java holds constants used by the common business flow classes for session keys, request keys
and error handling. For example, the session key to obtain the session state object resides in this file.
\\revcs\devref\Concorde\webapp\admin\WEB-
INF\classes\com\dstsystems\concorde\presentation\admin\commonModules\bf\web\common\BFConstants.
java

This class is not intended to hold all of the flow name and session variable name constants. A file exists in
the business package to hold all of these constants for the enterprise.
\\revcs\devref\Concorde\com\dstsystems\concorde\business\BusinessFlowConstants.java

3. ActionForm Classes
ActionForms should follow the same basic strategy as previously implemented.
 ActionForms should contain one or more DTOs that are copies of those on the session state.
 No additional getters and setters should be required in the ActionForm except for fields where
extra conversions or validation must be done (i.e. dates, immutable fields).
 The validate method in the ActionForm should call the validate method on the DTO.
This strategy assumes that the DTOs are implemented in the following manner:
 None of the getters and setters in the DTO should throw exceptions or do any validation.
 All validation should be done in the validate method in the DTO.
 When a setter method is called on the DTO, the DTO creates a snapshot if necessary. This way
the snapshots are only created once and only when needed. The clients will not have to worry
about when to make snapshots and they do not have to be created on the application tier.

Basic field level validations (e.g. numeric only fields) should still be performed in the JSPs.

4. Action Classes
Common code has been developed that handles all interactions with Business Flow. The following action
classes are now in PVCS in the following location: \\revcs\devref\Concorde\webapp\admin\WEB-
INF\classes\com\dstsystems\concorde\presentation\admin\commonModules\bf\web\frontController

4.1. InvokeBusinessFlowAction
This class will invoke the business flow with the flowName (BFConstants.
FLOW_NAME_REQUEST_KEY) sent on the request. It handles all interaction with the Business
Flow business delegate. It obtains the session state object from the session and places the updated
session state back on the session after the call is complete.
If the business flow call fails, nothing is saved on the session state. It is up to the developer to make
sure that the session state is cleaned up at the appropriate times.

9/3/2010 Page 1 of 6
 4.2. Subclasses of InvokeBusinessFlowAction
Various classes have been created to allow the appropriate error message to be supplied if a business
flow error occurs. Some common error messages have been identified that will be used across all
components for flows that perform functionality like retrieving summary information (e.g. for list
screens), retrieving detailed information (e.g. for the add/modify entity screens), saving information,
finding information, etc. These common behaviors each have a subclass that defines the error message
for that action.
The following classes currently exist:
 InvokeFindBusinessFlowAction – used when invoking a business flow call that performs
a search for information that is initiated by the user pressing a Find button.
 InvokeRetrieveDetailBusinessFlowAction – used when invoking a business flow that
retrieves the detailed information about an entity. This would usually occur when the user
selects to Modify or View an entity.
 InvokeRetrieveSummaryBusinessFlowAction – used when invoking a business flow that
retrieves summary level data or initializes a screen. This should be used for calls to obtain
data for list screens or for initialization of an entry point.
 InvokeSaveBusinessFlowAction – used when invoking a business flow to save the
modified information. Using this type of action requires two forward paths: success and
ghost_update. If the save fails due to a GhostUpdateChainedException, then you will often
need to forward to a different path to retrieve the data again.
 InvokeValidateBusinessFlowAction – used when invoking a business flow that calls an
API that performs validation only.

If additional types of flows that are component specific are needed, the InvokeBusinessFlowAction
should be subclassed in the component’s FrontController package to provide the correct error message.
Component specific subclasses should not be placed in the commonModules packages.

5. Session State
The session state resides on the session under the BFConstants.SESSION_STATE_KEY. The session state
should be kept pure, meaning that only data retrieved from the application tier or data that has been
validated locally should be placed on the session state.
Do not update a DTO on the session state directly until it has been validated.
The following action classes manage the session state and are now in PVCS in the following location:
\\revcs\devref\Concorde\webapp\admin\WEB-
INF\classes\com\dstsystems\concorde\presentation\admin\commonModules\bf\web\frontController

5.1. InitializeSessionStateAction
This class is used to create the session state object and place it on the session. This action should be
one of the first actions in the chain for initialization of an entry point in the application.

5.2. UpdateSessionStateAction
This common class updates the session state object with one or more key/value pairs specified on the
request. It should only be used for values that are of types that can be fully constructed using a String.
For example, setting the retailer ID as a java.util.Long is possible since a Long can be instantiated by
passing in a String value. For more complex updates where the object can’t be constructed with a
String argument, custom Update actions must be written for each component.
 The dataKey (BFConstants.DATA_KEY_REQUEST_KEY) specifies the key(s) to be
updated in the hash map in the session state.
 The dataValue (BFConstants.DATA_VALUE_REQUEST_KEY) specifies the value(s)
to be stored. The value is sent as a string representation of the value.
 The dataType (BFConstants.DATA_TYPE_REQUEST_KEY) specifies the type(s) of
the value to be stored. The type is the fully qualified name of the class to be created. The
class must have a constructor that takes a string since the UpdateSessionStateAction will

9/3/2010 Page 2 of 6
 attempt to construct an instance of the object with the dataValue and place it on the session
state.

Multiple values may be passed when separated by a semicolon

(BFConstants.DATA_DELIM_REQUEST_KEY).
For example, you could pass the following on the request:
 dataKey=retailerId;retailerName
 dataValue=1;DIRECTV
 dataType=java.util.Long;java.lang.String

Values may be removed from the session state using this class as well. If only the dataKey is specified
with no dataValue or dataType, the entry or entries associated with dataKey will be deleted.

6. Basic Flow
Struts actions will continue to be chained together to perform the required steps needed for many situations.
By writing the actions as small units of work, it is easier to reuse the actions and to insert new ones into the
flow.
In general, the flow is as follows:
Update Session State  Invoke Business Flow  Populate or Format Data  Display JSP

6.1. Update Session State

In general there will be an Update action that updates (or creates) key/value pairs on the session state
for the arguments needed by the API or APIs that will be called by the Business Flow. Custom Update
action may be written to accomplish this or the common UpdateSessionStateAction may be used and
the values passed in on the request.

There are two kinds of Update actions:

1. Updates for retrieving data – These typically have the word “Criteria” in the name, indicating
that they are for updating the session state with arguments used to retrieve data. For example:
UpdateMessageCriteriaAction is used when the user selects to find messages.

This type of Update action may handles caching of data by adding logic that checks for the
existence of the desired data on the session state and forwards to the Invoke Business Flow
action only if the call is needed. Otherwise it forwards directly to the Populate/Format action.
Often, the first thing this class does is to cleanup any session and session state data from
previous calls.

2. Updates for saving data – These updates place modified data on the session to be saved by the
next call to invoke a business flow. An example is UpdateMessageAction.

This type of Update action takes the DTO from the ActionForm and checks to see if it isNew
or isModified. If changes have been made, it forwards to the Invoke Business Flow path,
otherwise it terminates the flow and returns to a known state, indicating that no changes were
saved on the status bar if needed.

6.2. Invoke Business Flow

After a successful Update, the appropriate Invoke business flow subclass is called based on the type of
action being performed. Each action forwards to a “success” path if the business flow does not throw
any exceptions.
If the business flow performs a save or any type of update to the database, there is a possibility that a
ghost update could have occurred. As a result, when using InvokeSaveBusinessFlowAction, you need
an additional path (“ghost_update”) to handle the ghost updates behavior.

9/3/2010 Page 3 of 6
 6.3. Populate/Format Data
After a successful business flow call, the appropriate Populate and/or Format actions are executed to
format the data before the JSP is displayed. The Populate action retrieves the returned data from the
session state and places form field data on the form along with the DTO(s) that represent the data on
the screen. The Format action retrieves the returned data from the session state and formats it for
display in by the table or tree applet. Format actions are only required when the JSP contains an
applet.

6.4. Examples
The following are examples of some basic chains using business flow:

6.4.1. Search Functionality

This sequence of action mapping would be invoked when the Find button is pressed on a Find
screen
1. Update the session state with the search criteria from the form. Uses a custom Update
action.
2. Call InvokeFindBusinessFlowAction, sending in the flowName as a request parameter. This
should be passed in the struts config as part of the forward of the previous action.
3. Call the appropriate Format action to format the results into a table and then forward to the
find screen.

The following is a sample struts-config mapping for the find functionality:

<!-- find_message.do: Update the session state with the search criteria data. -->
<action path="/find_message"

type="com.dstsystems.concorde.presentation.admin.ccg.web.frontController.UpdateMessageCriteri
aAction"
name="findMessagesActionForm" scope="session" validate="false"
input="/ccg/find_message_main.jsp">
<forward name="success" path="/invoke_get_messages.do?flowName=CCG_getMessages" />
</action>
<!-- invoke_get_messages.do - Execute a search given the entered criteria. -->
<action path="/invoke_get_messages"

type="com.dstsystems.concorde.presentation.admin.commonModules.bf.web.frontController.InvokeFindBu
sinessFlowAction"
name="findMessagesActionForm" scope="session" validate="false"
input="/ccg/find_message_main.jsp" >
<forward name="success" path="/format_message_results.do" />
</action>
<!-- format_message_results.do - Format the results table with the list of messages. -->
<action path="/format_message_results"

type="com.dstsystems.concorde.presentation.admin.ccg.web.frontController.FormatMessagesAction"
name="findMessagesActionForm" scope="session" validate="false"
input="/ccg/find_message_main.jsp" >
<forward name="success" path="/ccg/find_message_main.jsp"/>
</action>

9/3/2010 Page 4 of 6
6.4.2. Add/Modify/Copy/View Entity Functionality
This sequence of action mappings would be invoked when the Add, Modify, Copy or View
buttons are pressed to cause the complete details of an entity to be displayed in a secondary
window or in the workspace of the primary window.
1. Update the session state with the ID of the entity for which the details are to be displayed.
Use a custom Update action or use the common UpdateSessionStateAction depending upon
the complexity of the update.
2. Call InvokeRetrieveDetailsBusinessFlowAction sending the flowName as a request
parameter. This should be passed in the struts-config as part of the forward of the previous
action.
3. Call the appropriate custom Populate action to populate the ActionForm for the secondary
window with the returned data from the session state and then forward to the JSP.

The following is an example of the struts-config mapping for this type of action:

<!-- display_message_details.do: Triggered by selecting the Modify, Copy or View buttons.

Updates the session state in preparation for the business flow call to retrieve the detail, invokes
the business flow call to get the detail, and then populates the screen with the detail needed for
the copy, modify or view action. -->
<action path="/display_message_details"

type="com.dstsystems.concorde.presentation.admin.commonModules.bf.web.frontController.U
pdateSessionStateAction"
name="messageActionForm" scope="session" validate="false" input="/close_modal.jsp?
returnValue=1">
<forward name="success"
path="/invoke_retrieve_message_details.do?
flowName=getCustomerCommunicationMessage"/>
</action>
<!-- invoke_retrieve_message_details.do: Gets the message details -->
<action path="/invoke_retrieve_message_details"

type="com.dstsystems.concorde.presentation.admin.commonModules.bf.web.frontController.Invo
keRetrieveDetailBusinessFlowAction"
name="messageActionForm" scope="session" validate="false" input="/close_modal.jsp?
returnValue=1">
<forward name="success" path="/populate_message.do"/>
</action>
<!-- populate_message.do: Prepare to show the secondary window containing the message
details. -->
<action path="/populate_message"

type="com.dstsystems.concorde.presentation.admin.ccg.web.frontController.PopulateMessageAc
tion"
name="messageActionForm" scope="session" validate="false" input="/close_modal.jsp?
returnValue=1">
<forward name="success" path="/ccg/message.jsp"/>
</action>

6.4.3. Save Entity Functionality

This sequence of action mappings would be invoked when the Save or OK buttons are pressed to
cause the data to be saved. The following example is for the OK button from a secondary
window.

<!-- save_message.do: Triggered by selecting the OK button on the message secondary window.
Update the session state with the modified values and validate the DTO, then call business flow to
save the message and return to the main window, updating it's state. -->

9/3/2010 Page 5 of 6
<action path="/save_message"
type="com.dstsystems.concorde.presentation.admin.ccg.web.frontController.UpdateMessageActi
on"
name="messageActionForm" scope="session" validate="true" input="/ccg/message.jsp">
<forward name="save" path="/invoke_save_message.do?
flowName=saveCustomerCommunicationMessage" />
<forward name="noSave" path="/close_modal.jsp?returnValue=0" />
</action>
<!-- invoke_save_message.do: Calls the business flow to save the message. -->
<action path="/invoke_save_message"

type="com.dstsystems.concorde.presentation.admin.commonModules.bf.web.frontController.Invo
keSaveBusinessFlowAction"
name="messageActionForm" scope="session" validate="false" input="/ccg/message.jsp">
<forward name="success" path="/close_modal.jsp?returnValue=0" />
<forward name="ghostUpdate" path="/invoke_retrieve_message_details.do" />
</action>
<!-- invoke_retrieve_message_details.do: Gets the message details -->
<action path="/invoke_retrieve_message_details"

type="com.dstsystems.concorde.presentation.admin.commonModules.bf.web.frontController.Invo
keRetrieveDetailBusinessFlowAction"
name="messageActionForm" scope="session" validate="false" input="/close_modal.jsp?
returnValue=1">
<forward name="success" path="/populate_message.do"/>
</action>
<!-- populate_message.do: Prepare to show the secondary window containing the message
details. -->
<action path="/populate_message"

type="com.dstsystems.concorde.presentation.admin.ccg.web.frontController.PopulateMessageAc
tion"
name="messageActionForm" scope="session" validate="false" input="/close_modal.jsp?
returnValue=1">
<forward name="success" path="/ccg/message.jsp"/>
</action>

9/3/2010 Page 6 of 6