|
| |
| Sun Java System Identity Manager 6.0 Deployment Tools 2005Q4M3 | |
1
Using the Business Process Editor
This chapter provides instructions for using the Business Process Editor (BPE). The information in this chapter is organized as follows:
OverviewThe Business Process Editor (BPE) is a standalone, Swing-based Java application that provides a graphical and forms-based view of Sun Java™ System Identity Manager workflows, forms, rules, generic and configuration objects, and views. Use the BPE when customizing Identity Manager for your environment.
You can use the Business Process Editor (BPE) to
Within the BPE, you create workspaces that are associated with specific repositories.
Starting and Configuring the BPE
Note To run the BPE, you must have Identity Manager installed on your local system and Configurator-level access to Identity Manager.
This section provides instructions for starting and configuring the BPE application, which includes:
Starting the BPE
To start the BPE from the command line:
- Change to the Identity Manager installation directory.
- Set environment variables with these commands:
set WSHOME=<Path_to_idm_directory>
set JAVA_HOME=<path_to_jdk>
Note If you are starting the BPE on a UNIX system, you must also enter
export WSHOME JAVA_HOME
- Change to the idm\bin directory and type lh config to start the BPE:
The Workspace location dialog displays, as follows:
Figure 1. BPE Workspace location Dialog
Use the Workspace location dialog to create a new workspace or to select an existing workspace. Instructions for both actions are provided in the next section.
Specifying a Workspace
A workspace is a mechanism for saving repository connection information (such as the default server and password), options, breakpoints set by the BPE debugger, open sources, and automatically saved files.
A workspace is tied to a specific repository. You can have more than one workspace associated with a repository, but only one repository per workspace.
The BPE has two different connections to the Identity Manager repository:
- Editor Connection — This connection is used by the classic Editor portion of the BPE.
The Editor connection can be LOCAL (where the Editor connects the directory to the repository using the ServerRepository.xml in WSHOME) or SOAP (where the editor connects via SOAP to the application server).
The LOCAL connection type enables you to edit objects in the repository when the application server is not running.
- Debugger Connection — This connection is used by the Debugger portion of the BPE to:
- Fetch source code from the application server
- Receive the current debugging state (variables, current location)
- Send commands to the debugger agent, which runs within the application server (setting breakpoints, sending step commands).
Because sending commands to the debugger agent requires a connection to a live application server, the only valid setting for the Debugger connection is SOAP. If you choose SOAP for the Editor connection, the debugger will use the same connection as the editor.
This section contains instructions for
Creating New Workspace
To create a new workspace,
- In the Workspace location dialog, enter a unique name for the new workspace in the Workspace Directory field, and then click OK.
When you provide the name of a workspace that does not yet exist, the Create new workspace wizard displays and instructs you to provide a directory for the workspace.
- Enter a directory name in the Workspace directory field, and then click Next.
The Connection Information dialog displays so you can specify connection information for your workspace.
Figure 2. BPE Connection Information Dialog
- Specify the Editor connection information as follows:
- Select a connection type:
- Local (selected by default): Select to enable the BPE to work on objects in a local repository.
When you specify a Local connection, BPE connects to the repository using the ServerRepository.xml found in WSHOME. (The SOAP URL field will be greyed out.)
- SOAP: Select to enable the BPE to work on objects in a different repository.
Note When you specify a SOAP connection, you will also be specifying SOAP as the default connection type for the BPE debugger.
- If you are using a SOAP connection, enter a fully qualified URL in the SOAP URL field. For example, http://localhost:8080/<idm>/servlet/rpcrouter2, where <idm> is the directory where you installed Identity Manager.
- Enable the Test Connection option if you want Identity Manager to test this connection to the repository.
- Specify the Debugger connection information for the BPE debugger as follows:
Note As mentioned previously, if you selected SOAP for the Editor connection type, you set the default debugger connection type to SOAP by default. All of the options in the Debugger connection area will be greyed out.
- Provide the following credentials:
- Click Finish to create the new workspace and the BPE main window will display.
Selecting a Workspace
Use one of the following methods to select an existing workspace from the Workspace location dialog,
After selecting a workspace, click OK and the BPE main window will display.
Troubleshooting Start-Up
When BPE tries to connect to the underlying server, you may receive the following error message:
HTTP 404 - /idm/servlet/rpcrouter2
Type Status report
message /idm/servlet/rpcrouter2
description The requested resource (/idm/servlet/rpcrouter2) is not available
If you get this connection error, check the URL field in the browser instance in which you are running Identity Manager. The first part of the URL listed there — for example, http://localhost:8080/idm — must be the same as the URL that you entered as the debugger connection.
Enabling JDIC
If you want to embed the web browser panel in the Form Preview panel, you must select JDIC as the preferred web browser. Otherwise, the Web Browser panel will use the External webbrowser command to launch the web browser externally.
To specify JDIC, use the following steps:
- Select Tools > Options to open the Editor Options dialog.
Figure 3. Editor Options Dialog
- Enable the JDIC option as the Preferred webbrowser. (This option does not display if the application is running a version of JRE less than 1.4.)
Notes:
- To enable JDIC for Windows, you must install Internet Explorer. (Mozilla is not currently supported on Windows.)
- To enable JDIC on Linux or Solaris, you must install Mozilla. At present, GNOME is the only supported desktop.
In addition, you must set the MOZILLA_FIVE_HOME environment variable to the root directory of your Mozilla installation.
To configure JDIC for Solaris 10+x86:
Using SSL in the BPE
To use SSL. in the BPE, open the Create new workspace wizard and change the SOAP URL protocol to https and the port number to your application’s SSL port.
Navigating the Business Process EditorBefore you start customizing Identity Manager processes or objects, you should know how to work with, view, and enter information and how to make selections in the BPE.
This information is organized into the following sections:
Working with the BPE Interface
The BPE interface includes a menu bar and dialogs for selections. The primary display is divided into two main panes:
Working in Tree View
The tree view (in the left interface pane) shows a hierarchical view of a task, form, view, or rule. This view lists each variable, activity, and sub-process in order, nesting actions and transitions under each activity.
The following example shows a sample tree view highlighting workflow.
Figure 4. BPE Tree View
Working with Additional Display Views
BPE provides the following additional display views:
The availability of these views depend upon the object type or process you select.
For example, the BPE presents a graphical display of a form as it would appear in a browser. This view complements the property view and XML display of unique form elements.
Note These views are introduced in the following sections.
For more detailed information about which display types are available for each Identity Manager object or workflow process, and how to work with these additional views, see Sun Java™ System Identity Manager Workflows, Forms, and Views.
Diagram View
For workflow, the Diagram view displays in the right interface pane, and provides a graphical representation of a process. Each icon represents a particular process activity.
Figure 5. Diagram View (Workflow)
Graphical View
The Graphical view displays in the lower right pane of the BPE display and shows the currently selected form as seen in a browser window.
Property View
The Property view displays in the upper right pane of the BPE display and provides information about elements in the currently selected form.
Figure 6. Property View (Form)
Loading Processes or Objects
To load an Identity Manager process or object use the following steps:
- Select File > Open Repository Object from the menu bar.
Tip You can also use the Ctrl-O shortcut. (See Keyboard Shortcuts, for a complete list of BPE shortcuts.)
- If prompted, enter the Identity Manager Configurator name and password in the login dialog, and then click Login.
The Select objects to edit dialog displays (similar to the following figure).
Figure 7. Select objects to edit dialog (with Library options expanded)
This dialog contains a list of objects, which can include the following object types.
Workflow Processes
Libraries
Workflow Sub-processes
Generic Objects
Forms
Configuration Objects
Rules
MetaViews
Email Templates
Note Items displayed may vary based on your Identity Manager implementation.
- Double-click an object type to display all of the objects that you have permission to view for that type.
- Select a process or object, and then click OK.
Setting Editor Options
You can set several options so that your preferences are reflected each time you launch the BPE. You can also set these options individually each time you work in the editor.
To set editor options, select Tools > Options to open the Editor Options dialog.
Figure 8. Editor Options Dialog
You can use the options on this dialog to specify the following preferences:
- Form Server Port — Specifies the default port for the HTML Preview page.
You use this page when you are editing forms.- Default Expression Style — Controls the display option for expressions in forms, rules, and workflows (Graphical or XML).
- Initial Dialog Tab — Controls the tab that appears on top (Main or XML).
- List Editor Style — Controls the default display of list expressions.
You can display lists in a table or as text boxes.- Disable Type Selector — Disables the Type Selector option that appears next to text boxes. The option to change types will still be available through the Edit dialog.
- Automatic Workflow Layout — Enables automatic layout of workflow activities the first time it is opened.
- Workflow Toolbox Style — Specifies where the Workflow Toolbox will be displayed relative to the main BPE window. Options include
- Preview Panel Context — Identifies the context in which information displayed in the Preview pane is rendered. Options include
- Auto-save interval (in seconds) — Specifies how many seconds the BPE will wait before auto-saving a session. (Default is 30 seconds)
- Preferred webbrowser — Specifies how to launch the web browser.
Options include:- External webbrowser command — Specifies the External webbrowser command to invoke the external web browser.
Validating Workflow Revisions
You can validate your workflow revisions at different stages of the customization process:
The BPE displays validation messages that indicate the status of the process:
Validate your workflow revisions as follows:
- Click an indicator to display its process action.
- After making changes, click Re-validate to re-test the process, confirm that the error is corrected, and check for additional errors.
- Drag your cursor into the Workflow diagram view.
The activity appears in the view.
Tip Any activities you create after the first activity are numbered. Re-number similar activities before creating more than two.
Saving Changes
To save your changes to a process or object and check it into the repository, select File > Save in Repository from the menu bar. When you select Save, the BPE saves the object in the location in which it was last saved (either in the repository or the file in which it was last saved). You can have multiple copies of the same object open.
Note You can use File > Save As File to save the object or process as an XML text file. Save the file in the form Filename.xml.
You can have multiple copies of the same object open in varying states and in different files or repositories.
Inserting XPRESS
If you are editing a rule, workflow, configuration or generic object, or form in the BPE XML pane, you can quickly insert an XML template for an XPRESS element wherever you have positioned the cursor.
- Position the cursor where you want to add the new XPRESS statement.
- Click the right mouse button to display the New menu.
- Select the type of XPRESS statement you want to add to the XML.
For example, select New > Logical > cond to add an empty cond statement at the cursor insertion point. The BPE displays the content-free cond statement, as illustrated in the following figure.
Figure 9. Menu for Inserting XPRESS Functions into XML
- Complete the statement as needed.
Note If you insert the XPRESS element in an invalid location, one or two red dots (indicators) display immediately to the left of the new code lines that mark the first and last lines of the inserted code. See Validating Workflow Revisions for information about these indicators.
Figure 10. Inserting XPRESS Function
Using Keyboard Shortcuts
The BPE supports these keyboard shortcuts for performing tasks.
Keyboard Command/Key
Action
Ctrl-O
Open (repository object)
Ctrl-S
Save (repository object)
Ctrl-X
Cut
Ctrl-C
Copy
Ctrl-V
Paste
Delete
Delete
Accessing JavadocsYou can access Javadocs for all public method classes from any BPE window that displays XML, as follows:
- Right-click in an XML window to display the cascading menu.
- Select New > Browse Javadoc.
Figure 11. Opening a Javadoc
- Select one of the following options from the cascading menu, which includes the following packages, subsequently broken down into component classes:
- com.waveset.object — Lists all the classes subordinate to this parent class.
- com.waveset.ui — Lists all the classes subordinate to this parent class.
- com.waveset.util — Lists all the classes subordinate to this parent class.
- com.waveset.util.jms — Lists all the classes subordinate to this parent class.
- All Classes — Displays the frames view of the Javadoc classes, from which you can navigate through each class in the browser.
Selecting one of these menu options opens a browser window that displays the class Javadoc.
Inserting a Method Reference
To insert a method invocation in the XML, access the method summary section of the class Javadoc. Click the Select button that precedes the method name under the Method Summary.
Figure 12. Selecting the getUser Method
At the cursor insertion point, BPE inserts the <invoke> element that you need to call the method from the XML.
Tip Click Validate for preliminary confirmation of the invoke statement syntax and XML.
Working with Generic and Configuration ObjectsThe fundamental object model for Identity Manager is the persistent object model. Because you perform almost all Identity Manager operations by creating an object, the persistent object API is the fundamental object model for customizing and controlling Lighthouse.
This section provides information about working with persistent objects. The information is organized as follows:
Common Persistent Object Classes
PersistentObject is the common base class of all persistent objects, and provides the fundamental object model for customizing and controlling Identity Manager. PersistentObject consists of a set of Java classes that are part of the infrastructure that is common to all persistent objects.
Viewing and Editing Objects
You can use the BPE to view and edit the two of the most commonly customized persistent object types:
- Configuration objects: A type of persistent object that contains forms and workflow processes.
- Generic objects: A configuration object that has an <Extension> of type <Object>. (In contrast to workflows, which are Configuration objects that have an <Extension> of type <WFProcess>.) You typically use Generic objects to represent views, and they are simple collections of name/value pairs. You can access these attributes externally through path expressions.
Note The following sections provide an introduction to the Configuration and Generic object types. For more detailed information, see Sun Java™ System Identity Manager Workflows, Forms, and Views.
Configuration Objects
You can directly access forms and workflows in the BPE; however, the BPE also provides access to other configuration objects that are not associated with a custom viewer. You can access these miscellaneous configuration objects from the BPE under the Configuration Object category.
The BPE lists these miscellaneous configuration objects in the left pane (tree view), as shown in the following figure:
Figure 13. BPE Tree Display of the Configuration Object
Double-clicking on an object name in tree view displays the Object window, which provides the following object views (tabs): Main, Repository, and XML.
For example, if you double-click User Extended Attributes in tree view, the following dialog displays:
Figure 14. User Extended Attributes Object Dialog
The BPE also displays configuration objects as unfiltered XML in the left pane of the BPE window. For example, see the following figure:
Figure 15. BPE XML Display of Reconcile Configuration Object
Generic Objects
Generic objects are simple collections of name/value pairs you can use to represent views. BPE displays these name/value pairs in column form and lists the attribute’s data type. Valid data types include Boolean, int, string, and xmlobject.
Figure 16. BPE Attribute Display of Generic Object (System Configuration)
Note Many customizations involve editing the System Configuration object, which is a type of generic object.
Creating a New Object
To create a new Configuration or Generic object
- Select File > New > GenericObject or Configuration Object.
The Configuration:New GenericObject or Configuration:New Configuration dialog opens, with the Main panel displayed.
- Enter the new object name in the Name field.
The BPE main window adds the new object name to the tree view. In addition,
- If you are creating a generic object, add an attribute as follows, repeating as necessary:
- Click New at the bottom of the Attributes pane. The BPE displays a new attribute field at the bottom of the list of attributes. Select New Attribute, then enter the name of the attribute.
- Assign a data type by clicking null in the Type column, and selecting a data type from the drop-down menu.
Figure 19. New Attribute of BPE Generic Object Display
Note To delete an attribute, click the attribute name, then click Delete.
- Select File > Save in Repository to save the new object to the repository.
Validating a New Configuration Object
You can immediately validate the new configuration object XML by clicking Validate, in the right pane of the main BPE window.
Debugging Workflows, Forms, and RulesThe BPE includes a graphical debugger for workflows, rules, and forms. You can use the BPE debugger to set breakpoints visually, execute a workflow or form to a breakpoint, then stop process execution and examine the variables.
If you have previously used a code debugger for a procedural programming language, you will be familiar with the terms used in this section.
Note For more information about views, workflow, forms see the relevant chapters in Sun Java™ System Identity Manager Workflows, Forms, and Views.
This section describes how to use the BPE Debugger, and is organized into the following sections:
Recommendations for Use
Use the BPE debugger under the following conditions only:
- Use in a development or test environment. Do not use the debugger in a production environment. Because setting a breakpoint is a global setting, incoming request threads are suspended when that breakpoint is reached.
- Assign user the Run Debugger right. (This right is granted as part of the Waveset Administrator capability.) The debugger can suspend threads (thereby potentially locking other users out of the system) and display variables, which possibly contain sensitive data, of other users’ sessions. Given the powerful repercussions of misusing this right, exercise caution when assigning it.
- Assign user a private copy of the application server. If two users are developing on the same application server and one user connects a debugger to it, the other user will hit their breakpoints during usage, and will be locked out.
Clusters are not supported for use with the BPE debugger.
Running the Debugger Outside a Test Environment
If you find a problem in production that requires debugging, reproduce and debug it in a test environment. Setting breakpoint in the debugger can quickly bring down the application server in a production environment, where a large volume of traffic occurs. In addition depending on where breakpoints are set, users can be blocked from using the system.
If you cannot debug in a separate test environment, follow this procedure:
- Divert all live traffic to a subset of your cluster by taking one of the nodes in your cluster offline. (For the purpose of this task, call this node server-a.)
- Use the BPE to edit the System Configuration object by setting the SystemConfiguration serverSettings.server-a.debugger.enabled property to true.
Note For information about accessing the System Configuration object with the BPE, see Step Two: Edit the System Configuration Object.
- Restart server-a so that the change to the System Configuration property setting can take effect.
- Launch the debugger by selecting Tools > Debugger.
- Create a new workspace, where the debugger connection uses the following URL:
server-a:<port>
When you have finished debugging
Disabling the Debugger
Always disable the serverSettings.server-a.debugger.enabled property in production to prevent someone from accidently connecting a debugger to the application server.
To disable the debugger, set the System Configuration object property serverSettings.<server>.debugger. to enabled=false.
Using the Debugger Main Window
The main debugger window displays the XML of the selected object and provides information about its execution. From this window, you can
- Start and stop the debugging process
- Navigate through the process execution
- Set distinct stopping points in process execution, or breakpoints. For more information about breakpoints, see Setting Breakpoints.
Figure 20. BPE Debugger: Main Window
The main window contains the following areas, which are described below:
Sources Area
The Sources area displays the unfiltered XML of the selected object.
The left margin of the XML panel displays a series of boxes that indicate points in the code where breakpoints can be set. Click the box immediately adjacent to the <WFProcess...> tag to set a breakpoint at the start of the workflow.
Figure 21. BPE Debugger Main Window Source Panel
Execution Stack
The Execution Stack identifies which function in the selected object is under execution. This area lists the executing function’s name and the name of the function that called it.
If additional functions appear in the call chain, these functions are listed in order. This list is also called a stack trace, and displays the structure of the execution stack at this point in the program's life.
Figure 22. BPE Debugger Main Window Execution Stack Panel
Variables Area
The Variables area lists all variables that are currently in scope at the current point of execution. Click on the variable object name to expand it and display the names of each variable.
Figure 23. BPE Main Window Variables Panel
Variables Not Available
The Variables Not Available area displays if debugging is inactive or if the selected stack frame is not the current stack frame.
Last Result
If the current element is an XPRESS end tag, the Last Result area contains the result of that evaluation. Also applies to other tags for which last value makes sense. For example, as <Argument>'s to workflow subprocesses are evaluated, this area has the value of that argument. This area is not available if debugging is not currently in progress.
Figure 24. BPE Debugger Main Window Last result Panel
Last Result Not Available
The Last Result Not Available area displays if debugging is inactive.
Keyboard Shortcuts
The BPE debugger supports these keyboard shortcuts for performing tasks.
Keyboard Command/Key
Action
Ctrl-O
Open (repository object)
Ctrl-R
Refresh Sources
F5
Select Current Line
F6
Step out
F7
Step into
F8
Step over
F9
Continue (Debugging)
Setting Breakpoints
A breakpoint is a command that the debugger uses to halt the execution of the object before executing a specific line of code. In the Identity Manager debugger, code breakpoints apply regardless of where the form or workflow is launched from.
While most debuggers allow you to set breakpoints only on source locations, the BPE debugger permits you to also set breakpoints at conceptual execution points, such as Refresh view. In this case, the debugger will suspend when a Refresh view operation occurs. You can then step-into the refresh view and see the underlying form processing in progress.
Setting a breakpoint is a global setting. That is, it causes the incoming request threads to suspend when the designated breakpoint is reached. This happens regardless of which user is making the request.
Setting a Breakpoint
To view a summary of all source breakpoints, click the Sources tab. The Breakpoints pane lists all source breakpoints. Navigate to a particular breakpoint by clicking the breakpoint in.
Types of Breakpoints
The Breakpoints area provides three types of breakpoint settings. Access these types of breakpoints by clicking the designated tab:
Select the Global tab to set code breakpoints by:
- All anonymous breakpoints. Use to set a breakpoint on an anonymous source.
- All named breakpoints. Breakpoints always supersede step-over and step-out functionality. Consequently, if you enable this setting, you have effectively turned step-over and step-out into step-into processing. In typical use, set All named breakpoints only if you do not know which form or workflow a given page uses. If you turn on this setting, turn if off immediately after the debug process identifies the form or workflow. Otherwise, you will be forced to step through every point of execution.
Checking both of these setting results in the debugger checking all breakpoints.
(Optional) Select a global setting, and click OK.
Figure 25. BPE Debugger Breakpoints Panel: Global Tab
Select the View cycle tab to set code breakpoints based on the view processing that occurs during process execution. The most commonly invoked view operations are listed in this dialog. Each of the listed view operations are available on each view.
Figure 26. BPE Debugger Breakpoints Panel: View Cycle Tab
Select the Form cycle tab to set code breakpoints based on a designated stage of form processing. For information about the stages of form processing, see Identity Manager Workflows, Forms, and Views.
Figure 27. BPE Debugger Breakpoints Panel: Form Cycle Tab
Stepping through an Executing Process
Stepping through describes the sequential, deliberate analysis of an executing process’ functions.
Terminology
Step into, step over, and step out are terms borrowed from debuggers of procedural programming languages, in which the execution order is implied by the structure of the language. However, in Identity Manager forms and workflow, the order in which elements occur in the code do not reflect the order in which they are executed.
Consequently, these terms have slightly different meanings as used in the Business Process Editor:
General Hints
Following is a list of hints to help you successfully step through an executing process:
- Set up stepping in the debugger to be as granular as feasible in the context of your debugging task. This practice helps you avoid missing anything potentially critical to debugging.
- Stepping does not change the execution order of your program. The program’s execution order is the same as it would be if the debugger were not attached. You can skip seeing portions of the execution (but they still execute regardless).
- Click step-into when you want the smallest step possible through the code.
- Click step-over when you feel that no probable problem exists with the content between the start and end tag. The debugger then skips this element although the code in between these tags still executes.
The following table provides snapshot of how the BPE debugger would proceed through this code sample:
<A>
<B/>
</A>
<D/>
(A, B, and D are some xml elements)
Getting Started
The BPE includes a tutorial on using the debugger with workflow, forms, and rules. The debugger ships with sample/debugger-tutorial.xml, which contains some sample workflows, rules, and forms. These samples are used throughout this chapter for tutorial purposes.
Step One: Import Tutorial File
Use one of the following methods to import the tutorial file:
After importing the file successfully, continue to the next section.
Step Two: Edit the System Configuration Object
To edit the system configuration object, use the following steps:
- From the BPE, open the System Configuration object for editing by selecting
File > Open Repository Object > Generic Objects > System Configuration.- In the tree view, expand serverSettings and the default attribute, and then select debugger.
- In the Attributes panel, click the Value column to enable debugging.
- Select File > Save In Repository to save your change.
- Restart your application server.
Caution Do not enable this property in production.
Step Three: Launch the Debugger
After restarting the application server, you can select Tools > Debugger to launch the BPE debugger.
Example: Debugging the Tabbed User Form and Refresh View
This section provides a sample debugging procedure to illustrate how debugger breakpoints apply regardless of where a form or workflow is launched from.
The sample procedure includes the following steps:
Setting a Breakpoint
To set a breakpoint:
Creating New User
To create a new user:
Viewing Before Refresh View Results
Return to the debugger frame, which is now suspended on the Refresh view breakpoint that you set. The Execution Stack lists Before Refresh View, which indicates the state of the view just before the refresh operation occurred. The Variables panel displays the view just before it has been refreshed.
Figure 28. Example 1: Debugging Suspended on Before Refresh View Breakpoint
Expand the global subtree and locate the firstname and lastname values that you typed in the form. Note that the fullname is currently null.
Viewing After Refresh View Results
To view the After Refresh view results,
- Click Continue.
The Execution Stack lists After Refresh View, which indicates that it now displays the state of the view just after refresh has occurred. Note that the fullname value is now jean faux.
Figure 29. Example 1: Debugging Suspended on After Refresh View Breakpoint
- Click Continue again.
The form has resumed execution. Return to the browser window. Change First Name to jean2 and click the Identity tab again to trigger another refresh.
- Return to the debugger frame.
Form processing is suspended at Before Refresh View.
Stepping Through the Form
To Step Through the form,
- Click Step-Into to reveal the fullname expansion in execution.
The debugger displays Before Expansion, which indicates that the form variables have not been expanded.
Figure 30. Example 1: Debugging Suspended Before First Expansion Pass
- Click Step-Into again.
The debugger displays Before Expansion, iteration=0, indicating that you will see the form variables before the first Expansion pass.
- Click Step-Into again.
The debugger is now on an anonymous source. The anonymous source is a wrapper form created on the fly and is related to the MissingFields form.
Figure 31. Example 1: Stepping-into the Start of Tabbed User Form
- Click Step-Into two more times until you reach the beginning of Tabbed User Form.
- Continue to click Step-Into until you reach <Field name='global.fullName'> (Approximately 20 to 30 step-into operations.)
- Click Step-into 15 times or until you have reached the </Field> element.
While stepping, the Last result at the </concat> tag is jean2 faux.
The form_outputs contains global.fullname: jean2 faux.
Figure 32. Example 1: Completed Debugging of Tabbed User Form
Complete Form Processing
To complete form processing:
- Click Step-out seven times.
At this point, your stack should indicate:
Refresh View (User)
After ExpansionThe Variables panel reflects the state of the form variables after all expansions have run.
- Click Step-out again.
You have now reached After refresh view. The variables now displayed are the view variables.
- Expand the global subtree.
Note that fullname is now jean2 faux.
- Click Continue.
Debugging Workflows
This section provides information about debugging your workflows.
The Workflow Execution Model
Workflows are executed by a single Java thread and are represented in the Execution Stack panel by a single Java thread. However, within a workflow, each activity becomes its own virtual thread.
During workflow execution, the workflow engine cycles through a queue of virtual threads. Each virtual thread is in one of the states described in the following table.
After all transitions have completed, the workflow process subsequently begins executing.
Example 1: Debugging a Workflow and a Rule
This example illustrates how to use the BPE debugger to debug a sample workflow and rule using a workflow provided in debugger-tutorial-workflow1 (supplied with Identity Manager). This example exemplifies how to step-into and step-through workflow debugging and rule execution.
You will complete the following steps:
Step One: Launching the Process
To launch the workflow debugging process:
- From the debugger main window, select File > Open Repository Object.
- Click debugger-tutorial-workflow1.
Note the small boxes in the left margin of the XML display. These boxes identify potential breakpoints that you can insert into the code.
Figure 33. Example 2: Setting the First Breakpoint
- Click the box adjacent to the <WFProcess> tag to set a breakpoint at the start of the workflow.
- Log in to Identity Manager and select Tasks > Run Tasks.
- Click debugger-tutorial-workflow1.
The debugger frame indicates that debugging has halted at your breakpoint.
Figure 34. Example 2: Debugging Halted at Breakpoint
Note the following:
- Execution Stack Panel — At the top of the Execution Stack panel, you see Thread [thread name] (suspended). This indicates that this workflow is currently being run by the thread of the given name, and that it is suspended at the breakpoint you set.
Below the Thread is your execution stack. This stack is an upside-down stack trace, with the calling function on top and the called function at the bottom. (It is upside down compared with how most debuggers represent execution stacks.)
The top most frame in the stack says Checkin View (ProcessViewer), which indicates that the workflow is being called by the checkinView method of the ProcessViewer. Because you do not have access to the Java source code for this stack frame, clicking on it will not display new information. However, it provides context as to where the workflow is being launched from.
The next frame in the stack is highlighted because it corresponds to the current point of execution, which is the beginning of the workflow process (<WFProcess>).
- Variables panel — Lists all variables that are currently in scope at the current point of execution. You will see
- Select Debug > Select Current Line (F5) to re-highlight your current line of execution.
Step Two: Starting Execution
To start execution:
- Click Step-Into.
At this point, the debugger moves to the start activity. Notice that the Execution stack contains a Virtual Thread [start, step=0] (executing), which indicates there is a Virtual Thread for the start activity that is currently in the executing state.
Figure 35. Example 2: Stepping-into the Execution of the First Virtual Thread
- Click two levels up on the debugger-tutorial-workflow-1 frame to highlight the WFProcess, showing you the location of the caller.
- Press F5 to return to the current line.
- Click Step-Into.
At this point, the debugger moves to the </Activity> and the start virtual thread is now pending outbound.
Step Three: Stepping Through the getFirstName Thread
Use the following procedure to step-through the getFirstName thread:
- Click Step-Into.
At this point, the debugger has highlighted the transition to getFirstName.
- Click Step-Into.
A new Virtual Thread for getFirstName has been created as a result of this transition. This Virtual Thread is currently in the ready state. The start virtual thread is still pending outbound (because this is an and-split operation, it must take all possible transitions).
Figure 36. Example 2: Stepping-into the Execution of getFirstName
- Click Step-Into again.
The debugger jumps to the getFirstName activity. The state changes from ready to executing.
- Click Step-Into.
The debugger moves to the get action.
- Click Step-Into three more times or until the debugger reaches the </set> tag.
The variables panel indicates that firstName has been set to myfirstname as a result of the </set>.
Step Four: Stepping Into and Over the getLastName Thread
Use the following procedure to step-into and over the getLastName thread:
- Click Step-Into three more times or until the debugger reaches the </Activity> for getFirstName.
The getFirstName virtual thread is now pending outbound.
- Click Step-Into.
The debugger returns to the start virtual thread, and is about to process the transition to getLastName.
- Click Step-Into.
The start has gone to inactive because all transitions have been processed. getLastName is now in the ready state because of this transition.
- Click Step-Into.
At this point, the start virtual thread will go away because it is inactive. Debugging moves to the getLastName virtual thread, which is now in the executing state.
- Click Step-Over to skip to the end of getLastName.
The lastName variable in the variables panel has been set to mylastname. Both the getFirstName and getLastName virtual threads are pending outbound.
- Click Step-Into.
The debugger is on the transition from getFirstName to computeFullName.
- Click Step-Into.
getFirstName goes to inactive and a new virtual thread, computeFullName is created. This thread is in the pending inbound state because it is still waiting on the inbound transition from getLastName. (The wait occurs because it is an and-join operation. If it were an or-join operation, process status would immediately go to ready.)
- Click Step-Into.
The debugger is now on the transition from getLastName to computeFullName.
Figure 37. Example 2: Debugger Transitioning from getFirstName to computeFullName
Step Five: Stepping Into computeFullName Processing
Use the following procedure to step-into computeFullName processing:
- Click Step-Into.
The computeFullName virtual thread goes from pending inbound to ready because of this transition.
- Click Step-Into.
computeFullName is now executing.
- Click Step-Into five more times.
The debugger is now on the </argument> tag for firstName. The last result panel shows <String>myfirstname</String>. This value is passed for the firstName argument.
Figure 38. Example 2: Stepping Into computeFullName Processing
Step Six: Stepping Through Rule Processing
To Step Through rule processing:
- Click Step-Into three more times.
The debugger steps into the Compute-Full-Name rule. In the execution stack, click the frame to move up one frame. The <rule> call in debugger-tutorial-workflow-1 is highlighted to indicate from where the rule is being called. Press F5 to re-select your current line.
- Click Step-Into three more times or until the debugger reaches the </ref> tag.
The last result panel shows <String>myfirstname</String>, which is the result of the <ref>firstName</ref>.
- Click Step-Into three more times or until the debugger reaches the </concat> tag.
The Last result panel displays the result of the <concat> expression.
<String>myfirstname mylastname</String>
- Click Step-Into twice more and Debugging returns to the </rule> tag.
Step Seven: Concluding Workflow Processing
To conclude workflow processing:
- Click Step-Into until you reach the </set> element.
The fullname variable has been updated to myfirstname mylastname.
- Click Step-Into twice more.
computeFullName is now pending outbound.
- Click Step-Into four more times. end goes to ready, then executing.
The debugger reaches the </WFProcess> tag, indicating that the process has now completed.
- Click Step-Into.
The Execution Stack displays After Checkin view, meaning that the checkin-view operation that launched this workflow has completed.
Figure 39. Example 2: Completion of Check-in View Operation
- Click Continue to resume execution.
If the browser request has not timed out, the Task Results diagram with the process diagram is displayed.
Example 2: Debugging a Workflow Containing a Manual Action and a Form
The following example illustrates how to use the debugger to debug a sample workflow containing a manual action. Use workflow2 from the debugger tutorial files.
- Select File > Open Repository Object.
- Expand Workflow Processes, and select debugger-tutorial-workflow2.
- Set a breakpoint on the <WFProcess...> tag.
- Log in to Identity Manager, and navigate to Tasks > Run Tasks.
- Click debugger-tutorial-workflow2.
The debugger has stopped at the breakpoint you set.
- Click Step-Into six times or until the debugger marks <ManualAction... name='getNameAction'>).
Figure 40. Example 3: Stepping Into a Manual Action
- Click Step-Into.
- When a dialog displays to explain that form processing occurs in a different thread, set a breakpoint on the <Form> tag to see the processing occur.
Figure 41. Example 3: Debugger Stepping Into Manual Action Popup Dialog
- Click Yes or Always.
After form processing has completed, the workflow continues execution in a separate thread. Consequently, you must set a breakpoint on the </ManualAction> to observe workflow processing after the form has completed processing.
Figure 42. Example 3: Breakpoint Marking Start of Form
Note that the debugger has set breakpoints on the <Form> and </ManualAction> tags as indicated. In addition, the execution stack indicates After checkin view... and you have stepped out of the workflow process because workflow processing has proceeded as far as possible (until the manual action completes).
- Click Continue, and the debugger stops processing at the breakpoint set on the <Form> element.
Figure 43. Example 3: Debugger Displaying Manual Action Processing
Note the following In the Execution Stack area:
- Checkout View (WorkItem:...) — Indicates that processing is occurring in the context of a checkout view for the given work item.
- ManualAction forms — Operate against the work item view and manipulate workflow variables through the variables object. Expand the variables object to see the non-null workflow variables.
- Derivation — Indicates that form execution is on the Derivation pass.
- Because this form contains no <Derivation> expressions, proceed to the next phase or processing by clicking Continue. The HTML Generation (root component) pass of form processing begins.
HTML Generation Phase (Root Component)
To generate HTML for the root component:
- Click Step-Into twice.
The debugger has just processed the title <Property> element. The Last result panel contains the value of this property.
- Click Step-Into three more times.
The debugger skips the fields in the form and goes directly to the </Form> element because this pass focuses only building the root component of the page.
- Click Continue.
The HTML Generation (subcomponents) pass of form processing begins.
HTML Generation (Subcomponents)
To generate HTML for the subcomponents:
- Click Step-Into 13 times or until the debugger reaches the </Form> tag.
The debugger iterates over each of these fields and evaluates their display properties.
- Click Continue.
The debugger displays No suspended threads because execution has resumed. Control has now returned to your browser window.
- Return to your browser window, and enter your first and last name as prompted, and click Save.
Return to your debugger frame. The debugger is now suspended on your breakpoint.
- Expand the Variables subtree.
The firstName and lastName are the values that you just entered. The debugger is currently in the Confirmation phase of form processing.
Figure 44. Example 3: Form Processing Confirmation Phase
Confirmation
Because this form has no confirmation fields, no processing occurs.
Click Continue to begin the Validation phase of form processing.Validation and Expansion
Because this form contains no Validation expressions, no obvious processing occurs.
- Click Continue to skip the Validation phase.
You are now on the Expansion phase of form processing.
- Click Step-Into six times.
The debugger is now on the <rule> tag of the <Expansion> of the variables.fullName field.
Figure 45. Example 3: Stepping Into Rule Processing
- Click Step-Into five times, and the debugger has now stepped into the <rule> element.
- Click Step-Into seven times or until the debugger reaches the </Rule> element.
The Last result contains the full name.
- Click Step-Into again and processing resumes in the form.
- Click Step-Into again.
The top-level variables.fullName has the value of the Expansion expression that just ran. This is top-level entity rather that a child of the variables data structure because during form processing, form outputs are kept in their own temporary form_outputs data structure, with path expressions flattened.
After form processing, form outputs are assimilated back into the view. In the implicit variables form_inputs and form_outputs, form_inputs shows the unmodified workitem view, and form_outputs shows the output fields that are assimilated back into the view after form processing completes.
Figure 46. Example 3: Debugger Displaying Completed Execution of variable.fullName
In general, form_inputs identifies the view, and form_outputs contains data to be assimilated back into the view. However, not all forms are necessarily tied to a view (for example, active sync forms). The form engine is a general data mapping engine, mapping from form inputs to form outputs. The view handler is responsible for passing the view into the form engine and assimilating the outputs back into the view.
- Click Continue.
The debugger reaches the </ManualAction> breakpoint, which was set before when the debugger stepped into the Manual Action. The variables firstName and lastName are the values that you entered. fullName is the result of the Expansion expression that was just run.
Figure 47. Example 3: Debugger Displaying the Result of Expansion Processing
- Click Step-Into five times until <ManualAction... name='displayNameAction'>.
- Click Step-Into again. (Click Yes or Always, if prompted.)
- Click Continue.
The debugger is now on the Derivation pass for displayNameForm.
Derivation and HTML Generation (Root Component)
To complete the derivation and HTML generate phase
- Click Continue to begin the HTML Generation (root component) processing for displayNameForm.
- Click Step-Into eight times or until the debugger reaches the </Property> element for subTitle.
- Click Continue twice.
The debugger displays the following message:
No suspended threads because execution has resumed. Control has now returned to the browser window.
- Return to your browser window.
The information displayed is the same you entered.
- Click Save and return to your debugger frame.
The debugger is now on the Confirmation pass, processing the displayNameForm.
Validation and Expansion
To begin validation and expansion,
- Click Continue to begin the Validation pass.
- Click Continue to begin the Expansion pass.
- Click Continue again.
The debugger is now on the </ManualAction> tag because the manual action is complete. At this point, workflow processing has resumed.
- Click Step-Into five times or until the debugger reaches the </WFProcess> tag, indicating that the workflow has completed execution.
- Click Continue.
The debugger displays the following message:
No suspended threads because resumed execution has resumed. Control has now returned to your browser window.
- Return to your browser window to observe the workflow process diagram.
Debugging Forms
Forms are processed in a series of passes. Depending on which pass is in progress, certain elements are processed and others are ignored. The Execution stack in the debugger main window indicates the current phase of form processing. The execution stack frame preceding the outermost form always has the name of the pass.
Derivation
During Derivation phase of form execution, the form engine iterates over each field. It also processes each <Disable> expression. For fields whose <Disable> expressions return false, you will also see it process the <Derivation> expression.
Expansion
The debugger iterates over each field and processes each <Disable> expression. For those fields whose <Disable> expressions return false, it processes the <Expansion> expression.
The Expansion processing phase continues to run until either
By default, maxIterations is set to one. Consequently, the debugger makes only one pass, which is why the Execution stack panel displays Expansion, iteration=0 when expansions are run.
Validation
The debugger iterates over each field, processing each <Disable> expression.
For those fields whose <Disable> expressions return false, the form engine also processes the following:
Confirmation
The debugger iterates over each field, processing each <Disable> expression. For those fields whose <Disable> expressions return false and that also have a confirm attribute, the debugger confirms that the field referenced by confirm matches this field. If the fields do not match, it adds an error to display.errors in the Variables panel.
Assimilation
The debugger iterates over each field and processes each <Disable> expression. For those fields whose <Disable> expressions return false, the debugger processes the <Property> objects of the field's <Display> element.
Note that this phase is typically skipped. It is relevant only for certain forms (such as the login form) that do not contain display.mementos. This is necessary for these forms to reconstruct the HTML components during post data assimilation.
HTML Generation (Root Component)
The debugger iterates over only the top level form and the form's <FieldDisplay> element. The goal of this pass is to build the top-level HTML component. HTML Generation (subcomponents) pass follows immediately.
HTML Generation (Subcomponents)
The debugger iterates over each field. It also processes each <Disable> expression. For those fields whose <Disable> expressions return false, the debugger processes the <Property> elements of the field's <Display> element.
Custom View Processing
Certain views require additional passes over the form. During these passes, the debugger iterates over each field and processes each <Disable> expression.
Working with Anonymous Sources
When stepping through forms, the debugger can identify an anonymous source. An anonymous source is a form (or portion of a form) that is generated on the fly. As a result, an anonymous source does not correspond to a persistent form that resides in the Identity Manager repository. (Examples of anonymous sources include the login forms and the MissingFields form.)
You cannot set individual breakpoints on an anonymous source because they do not reside in the Identity Manager repository and thus lack a unique identifier.
However, you can step through an anonymous source.
To set a breakpoint on all anonymous sources, select the Global tab in the Breakpoints panel. The debugger subsequently breaks any time it encounters a line from an anonymous source. For example, to debug the login form, select this option, and go to the login page.
