|
| |
| Sun[TM] Identity Manager 8.0 Deployment Tools | |
Appendix A
Using the Business Process Editor
Note
The Business Process Editor (BPE) is deprecated, and will be removed in the next Identity Manager release. Please use the Identity Manager IDE instead.
This appendix 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 Identity Manager workflows, forms, rules, generic and configuration objects, and views.
You use the BPE to customize Identity Manager for your environment as follows:
- View, edit, and create forms, workflows, rules, email templates, and rule libraries
- View and edit configuration objects and generic objects
- View JavaDocs for the classes that comprise the Identity Manager public APIs
- Debug forms, workflows, and rules
- 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, including:
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>To start 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 shown in Figure A-1.Figure A-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:
This section contains instructions for
Creating New Workspace
To create a new workspace, use the following instructions:
- 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 A-2 BPE Connection Information Dialog
- Specify the Editor connection information as follows:
- Select a connection type:
- If you are using a SOAP connection, enter a fully qualified URL in the SOAP URL field. For example, http://host:port/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:
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.
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 must be the same as the URL that you entered as the debugger connection. For example, http://host:port/idm.
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:
To configure JDIC for Solaris 10+x86:
- Download jdic-0.9.1-bin-cross-platform.zip from https://jdic.dev.java.net.
- Extract the zipped files.
- Replace the <wshome>/WEB-INF/lib/jdic.jar
with the jdic-0.9.1-bin-cross-platform/jdic.jar.- Copy jdic-0.9.1-bin-cross-platform/sunos/x86/*
to <wshome>/bin/solaris/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
Tree view (in the left pane) provides a hierarchical view of tasks, forms, views, or rules. This view lists each variable, activity, and subprocess in order — nesting actions and transitions under each activity. Figure A-4 shows a sample tree view highlighting workflow.
Figure A-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.These views are introduced in the following sections.
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 A-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 A-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 Using 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 and it contains a list of objects, which can include the following object types.
- 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 A-7 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:
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 in varying states and in different files or repositories.
Note
You can also use File > Save As File to save the object or process as an XML text file. Save the file in the form Filename.xml.
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 A-8 Menu for Inserting XPRESS Functions into XML
- Complete the statement as needed.
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 A-9 Inserting XPRESS Function
Using Keyboard Shortcuts
The BPE supports these keyboard shortcuts for performing tasks.
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 A-10 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 A-11 Selecting the getUser Method
At the cursor insertion point, BPE inserts the <invoke> element that you need to call the method from the 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.
These common PersistentObject classes include:
- Type: A set of constants used in many methods to indicate the type of object being referenced.
- PersistentObject: The common base class of all repository objects. The most significant properties are the identity, member object groups and the property list.
- ObjectRef: When an object references another, the reference is encoded in this object. The reference includes the object type, name, and repository identifier.
- Constants: A collection of random constants for many different system components.
- ObjectGroup: A group representing an organization in the Identity Manager interface. All persistent objects must belong to at least one object group. If you do not specify otherwise, the object is placed in the Top group.
- Attribute: A collection of constant objects that represents common attributes that are supported by objects. Often used internally when building object queries. When a method accepts an Attribute argument, there is usually a corresponding method that takes a string containing the attribute name.
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.
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 A-12 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 A-13 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 A-14 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 A-15 BPE Attribute Display of Generic Object (System Configuration)
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 A-18 New Attribute of BPE Generic Object Display
- 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.
Creating and Editing RulesYou can use the BPE to
This section provides information and instructions for using the BPE to create and edit rules. The information is organized as follows:
Note
Instructions for starting the BPE application are provided in Starting and Configuring the BPE.
Using the BPE Interface
Before you start customizing rules, you must understand the basics of navigating and using the BPE interface. When you are working with rules, the initial BPE interface consists of display panes, a menu bar, Action menus, and Rule dialogs.
This section describes the interface related to creating and editing rules. The information is organized as follows:
BPE Display Panes
When you are working with rules, the BPE interface provides the following display panes:
Tree View
The tree view (in the left interface pane) lists selected rules as standalone icons.
Figure A-19 Rule Display in Tree View
Typically, the tree view shows a hierarchical view of tasks, forms, or views — listing each element in order with sub-elements nested under their parent.
However, rules do not reside in hierarchies within Identity Manager (unless already incorporated into a rule library object, workflow, or form), so there are no hierarchical relationships among rules to display in tree view. Instead, rules that are not incorporated into a library, workflow, or form appear in tree view as single icons.
Rule Source
The Rule source pane (in the upper right interface pane) provides the source information of a rule.
Figure A-20 Rule Source Pane
From this pane, you can right-click to access a cascading menu that enables you to perform any of the following tasks:
You can also use the buttons located above this pane to perform any of the following actions:
Input Tab
The Input tab pane (located in the lower right corner of the window) displays by default.
Figure A-21 Input Tab Pane
You can use this tab to control the arguments that are passed to the rule for testing. This tab is basically the same as the BPE's GenericObject Editor (see Generic Objects).
From this pane, you can:
- Double-click the argument name, the Arguments dialog displays so you can Validate the argument.
- Right-click an argument name to access a cascading menu that enables you to import test data from a view or a file. Specifically, you can perform any of the following tasks:
- Click New to create new arguments by specifying a name, type, and value.
- Click Delete to delete a selected argument.
Result Tab
Select the Result tab and click Run (above the Rule source pane) to execute the selected rule. The rule’s return value displays in the Result tab pane in XML format.
Figure A-22 Result Tab Pane
Trace Tab
Select the Trace tab to capture XPRESS tracing during execution of the rule.
Figure A-23 Trace Tab Pane
Menu Selections
You can use the menu bar or the action (right-click) menu to work in the interface.
Select an item in the tree or diagram view, and then right-click to display the action menu selections that are available for that item.
Rule Dialogs
Each rule and rule element has an associated dialog that you can use to define the element type and its characteristics.
To access these dialogs, double-click the rule name in the tree view. The rule dialog for the selected rule displays, with the Main tab in front by default. For example, see the following figure:
Figure A-24 Rule Dialog (Main Tab View)
You use the options on this dialog to define a rule, as follows:
- Name: Automatically displays the selected rule name, which is the name displayed in the Identity Manager interface.
- Description (optional): Specify text describing the purpose of the rule.
- Comments: Specify text inserted into the rule body with a <Comment> element.
- Arguments: Specify any required arguments.
Editing Rule Elements (Changing Field Value Type)
Some dialog fields behave differently depending on the field value type you selected.
You can use one of the following methods to change a value type:
Changing Display Type
To change the way information displays in diagram view
- Right-click to display the action menu.
- Select Display > <view_type>.
The view types include:
- XML – Displays XPRESS or JavaScript source. You may prefer this display type if you are comfortable with XML.
Figure A-26 XML Display
- Graphical – Displays a tree of expression nodes. This display type provides a structural overview.
Note
To conserve space, Figure A-27 shows only part of the selected rule.
Figure A-27 Graphical Display
- Property Sheet – Displays a list of properties, some of which can be edited directly.
- Configuration – Displays argument information listed in a property-sheet style. (See Figure A-29.) Also lists any comments that the rule creator used to describe the rule in the database.
Figure A-29 Configuration Display
Browsing Rules
Use one of the following methods to browse and select the rules that you can access through Identity Manager:
When the Select Rule dialog opens (Figure A-30), expand the Rules node to display the available rules.
Figure A-30 Select Rule Dialog
Reviewing Rule Summary Details
Double-click a rule name in the tree pane to view, at a glance, rule elements.
The Rule dialog contains the following tabs:Main Tab
Select this tab to access argument properties for this element (including each argument’s name and value). It also lets you re-order arguments for better visual organization. (Reordering in this list does not change interpretation of the rule.)
The Main tab displays the same information about the rule as the Main view of the Rule dialog (see Figure A-31).
Figure A-31 Main Tab Display
Repository Tab
Select the Repository tab to view the following information about the selected rule:
Figure A-32 Repository Tab Display
The Repository tab primarily contains read-only information, but you can change the following values:
Rules have no subtype by default. Consequently; when you create a rule, the Subtype value defaults to None.
However, to display this rule in the Reconciliation interface, you must set this value to Account Correlation or Account Confirmation, depending upon which selection list in the Reconciliation graphical user interface you would like this rule to appear.
- Organization: Enter a new organization assignment into the text field.
- Authorization Type: Enter a new authorization type into the text field.
Note
For an example rule subtype, see “ExcludedAccountsRule” on page 48.
XML Tab
Select the XML tab to view and edit raw XML for the selected rule. You can then click Validate to validate your changes before clicking OK to save. The XML parser validates the rule XML against the waveset.dtd.
Figure A-33 XML Tab Display
Creating a New Rule
Use the following steps to create a new rule:
- Select File > New > Rule. and the Rule: New Rule dialog displays, with the Main tab in front by default.
Figure A-34 New Rule Dialog
- Specify the following parameters for the new rule:
- Click New to add arguments to the new rule.
- When the Argument: Null dialog displays, enter text into the Name, Value, and Comments fields, and then click OK.
This text displays in the Arguments table and will be inserted into the rule as a <RuleArgument> element.
- When you are finished click OK to save your changes.
Defining Rule Elements
The XML elements that comprise rules can be functions, XPRESS statements, one of several data types. You can use the following BPE Rule Element dialogs to create or edit rule elements:
- Argument dialog — Use to view or define argument characteristics.
- Element dialog — Use to view or define selected elements.
- Object Access dialog — Use to manipulate objects or call Java methods that manipulate objects.
- Diagnostics dialog — Use to debug or examine JavaScript, trace, print, and breakpoints.
Additional information about these dialogs is provided in the following sections.
Note
For more information about rule structure, see “Understanding Rule Syntax” on page 13.
Argument Dialogs
You use an Argument dialog to access and define rule arguments.
Figure A-35 Argument Dialog
Use one of the following methods to open an Argument dialog:
- From the Tree view pane, double-click a rule name to open the Rule dialog, and then double-click the argument name on the Main tab.
- From the Rule source pane (in Graphical View only), right-click and select
New > Rule > argument.- From the Rule source pane (in Graphical view only), double-click an argument node.
Figure A-36 Double-Click an Argument Node
The Argument dialog provides the following basic options:
In addition to the preceding options, the Argument dialog may also display other fields depending upon the type of element you are viewing/editing.
For example, if you are viewing a method element, an Argument dialog similar to the one displayed for the Query method dialog opens:
Figure A-37 Argument Popup Dialog (Method)
You can change the argument’s data type by clicking the Change Type button, which displays the Select Type dialog.
Figure A-38 Select Type Dialog
Valid argument types are listed in the following table.
Element Dialogs
The Element dialog displays the name and value of an argument.
Figure A-39 Element Popup for the address Variable
Use one of the following methods to display an Element dialog from the Rule source pane (in Graphical view only):
If you open a dialog by clicking the argument name, you can change the argument’s data type and style (simple or calculated).
You can define several types of elements (see Table A-4). To change the data type of the element, click the Change Type button. The Select Type popup opens, displaying a list of the data types you can assign to the selected rule element.
To create a new element, right-click in the Graphical view and select
New > <element_type> from the menu. The element types listed on this menu represent categories of XPRESS functions.
Note
For more information about these functions, see Sun Java™ System Identity Manager Workflows, Forms, and Views.
You can also access the element types most recently created in a BPE session through the Recent options of the actions menu.
The following figure shows the window that displays when you select
New > Strings > concat.Figure A-40 concat Dialog
Object Access Dialogs
Use an Object Access dialog to manipulate objects or call Java methods that manipulate objects.
To open an Object Access dialog, right-click anywhere in the graphical display and select New > Other > Object Access > option from the pop-up menu.
Where option can be any of the following options described in Table A-5:
To create an object, right-click to access the action menu, and select New > Other > Object Access > new.
Figure A-41 new Dialog
Editing Element Details
From the Argument dialog, you can define values for the variable. Use the Value field to enter a simple string value as the initial variable value. Alternatively, you can select a value type (such as Expression or Rule), and then click Edit to enter values.
Figure A-42 shows the variable window for a ref statement.
Figure A-42 ref Dialog
To identifying argument types (simple or complex), select Simple when you can enter the argument value in a text field (for example, string, Boolean, or integer). If you are working with a List, XML Object, or other expressions that requires an additional popup, select Calculated.
Diagnostics Dialogs
You can use Diagnostics dialogs to debug or examine the following:
To access the Diagnostics dialog, select New > Other > Diagnostics > trace from the actions menu in the right pane. Select an option described in Table A-6 to debug that item.
Editing a Rule
If you customize a rule, you must save and validate your changes to ensure that the rule completes correctly and as expected. After saving, import the modified rule for use in Identity Manager.
This section provides instructions for the following:
Loading a Rule
Use the following steps to load a rule in the BPE:
- Select File > Open Repository Object from the menu bar.
- If prompted, enter the Identity Manager Configurator name and password in the displayed login dialog, and then click Login.
The following items display:
- Expand the Rule node to view all existing rules.
- Select the rule you want to load, and then click OK.
Saving Changes
To save changes to a rule and check it into the repository, select File > Save in Repository from the menu bar.
Note
You can also use File > Save As File to save the rule as an XML text file. Save the file in the form Filename.xml.
Validating Changes
You can validate changes to rules at different stages of the customization process:
- From the Rule source pane, click the Validate button to validate the rule with the current set of arguments.
- If you are working with XML display values, when adding or customizing arguments, click Validate to validate each change to the rule.
- After making changes, select the rule in the tree view, and then select Tools > Validate to test it.
The BPE displays validation messages that indicate the status of the rule:
Rule Libraries
A rule library serves as a convenient way to organize closely related rules into a single object in the Identity Manager repository. Using libraries can ease rule maintenance by reducing the number of objects in the repository and making it easier for form and workflow designers to identify and call useful rules.
A rule library is defined as an XML Configuration object. The Configuration object contains a Library object, which in turn contains one or more Rule objects. Code Example A-1 shows a library containing two different account ID generation rules:
You reference rules in a library using an XPRESS <rule> expression. The value of the name attribute is formed by combining the name of the Configuration object containing the library, followed by a colon, followed by the name of a rule within the library.
For example, the following expression calls the rule named First Dot Last contained in a library named Account ID Rules:
<rule name='Account ID Rules:First Dot Last'/>
Selecting a Library to View or Customize
Perform the following steps to select a rule library to view or edit:
- From the Business Process Editor, select File > Open Repository Object.
Rule libraries are represented in the BPE with this icon
:
- Select the rule library object in the Tree view, and select Edit.
- Right-click inside the right edit pane, and then select the XML tab.
Figure A-43 Rule Library (XML View)
You can now edit the rule library XML.
Adding a Rule to an Existing Library Object
Once a rule library has been checked out, you can add a new rule by inserting the <Rule> element somewhere within the <Library> element. The position of the Rule within the library is not significant.
Customizing a Workflow ProcessThis section uses an Email Notification example to illustrate the end-to-end steps you follow to customize a workflow process. Specifically, you will:
- Create a custom Identity Manager email template
- Customize the Identity Manager Create User workflow process to use the new template and to send an email welcoming the new user to the company
Note
- Illustrations provided in this example may differ slightly from those you see when you load a process. Discrepancies can result in different component positioning or the selective removal of process actions that are unimportant to the example.
- Though you can perform many tasks from the tree view or diagram view, this example primarily uses BPE’s tree view.
Step 1: Create a Custom Email Template
To create the custom email template, open and modify an existing Identity Manager email template as follows:
- From the BPE menu bar, select File > Open Repository Object > Email Templates.
- When the selection dialog displays (Figure A-44), select the Account Creation Notification template and then click OK.
Figure A-44 Selecting an Email Template
- When the selected email template displays in the BPE, right-click the template name and select Copy from the pop-up menu.
- Right-click again and select Paste.
A copy of the email template appears in the list view.
Tip
When pasting, be sure the mouse does not cover an item and that no items are selected (or the paste action will be ignored).
- Double-click the new email template in list view to open the template.
- Change the template name by typing User Creation Notification in the Name field.
Figure A-45 Renaming the New Template
- In the newly created User Creation Notification template, modify the Subject and Body fields as needed.
Figure A-46 Customizing the User Creation Notification Email Template
You can also add a comma-separated list of Identity Manager accounts or email addresses to the Cc field.
- When you are finished, click OK.
- To save the template and check it into the repository, select File > Save in the Repository from the menu bar.
Now you are ready to modify the Create User workflow process. Continue to the next section for instructions.
Step 2: Customize the Workflow Process
Use the following steps to modify the Create User workflow process to use the new email template:
- Load the workflow process from the BPE by selecting File > Open Repository Object > Workflow Processes.
A dialog appears that contains the Identity Manager objects you can edit.
- Select the Create User workflow process, and then click OK.
Figure A-47 Loading the Workflow Process
The Create User workflow displays.
- In tree view, right-click the Create User process and select New > Activity from the pop-up menu.
Figure A-48 Creating and Naming an Activity
A new activity, named activity1, displays at the bottom of the activities list in the tree view.
- Double-click activity1 to open the activity dialog.
- Type Email User in the Name field to change the activity name.
In the default Create User workflow, the step that notifies account requestors that an account was created (Notify) transitions directly to end.
To include a new step in the workflow, you must delete this transition and create new transitions (between Notify and Email User, and from Email User to end) to send email to the new user before the process ends.
- Right-click Notify, and then select Edit.
- In the Activity dialog Transitions area, select end and then click Delete to delete that transition.
- In the Transitions area, click New to add a transition.
- When the Transition dialog displays, select Email User from the list and then click Done.
Figure A-49 Creating and Modifying Transitions
- In the BPE tree view, right-click Email User, and then select New > Transition to create a transition and open the Transition dialog.
- Select end, and then click OK.
- Next, you must create an action for the new Email User activity that defines the email action and its recipient. In the tree view, right-click Email User, and then select New > Action to open the Action dialog.
- Enable the Application button for the Type option.
- Type a name for the new action in the Name field.
- Select email from the Application menu.
Figure A-50 Creating an Action
- New selections display in the Arguments table. Enter the following information:
- Click New to add an argument to the table. Name the argument accountId and enter the $(accountId) value for this argument.
Figure A-51 Creating an Action
- When you are finished, click OK.
- Select File > Save in the Repository from the BPE menu bar to save the process and check it back into the repository.
After saving, you can use Identity Manager to test the new process by creating a user. For simplicity and speed, do not select approvers or resources for the new user. Use your own email address (or one that you can access) so that, upon creation, you can verify receipt of the new welcome message.
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.
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.
See Step Two: Edit the System Configuration Object for more information about accessing the System Configuration object with the BPE.
- 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
- Set serverSettings.server-a.debugger.enabled to false and restart server-a to prevent the debugger from connecting to your live production environment.
- Reintegrate server-a into your on-line cluster.
Disabling the Debugger
You must 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 A-52 BPE Debugger: Main Window
Note
The BPE debugger provides numerous keyboard shortcuts for performing tasks. See Using Keyboard Shortcuts for a list of these shortcuts.
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 A-53 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 A-54 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 A-55 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 A-56 BPE Debugger Main Window Last result Panel
Last Result Not Available
The Last Result Not Available area displays if debugging is inactive.
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 the following types of breakpoint settings:
Access these breakpoint types by selecting the designated tab.
- Select the Global tab to set code breakpoints by:
Breakpoints 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.
- 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 A-58 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 Sun Java™ System Identity Manager Workflows, Forms, and Views.
Figure A-59 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 when used in the Business Process Editor:
- Step-into: Describes moving to the next point of execution on the current thread. Step-into must be the smallest amount by which you can proceed through a process in the debugger XML display.
- Step over: Describes moving from the current begin tag to the current end tag without stopping at an interim element. Stepping over permits you skip almost everything between a start and end tag. However, if the next point of execution does not occur between the start and end tags of the current element, debugging halts there instead.
For example, in a workflow containing multiple active virtual threads, you can step to the start tag of an action, but the next element to be executed is a different action. In this case, the process stops executing at a different point. Thus, you avoid accidently skipping over a potentially significant element.
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.
Table A-7 provides a snapshot of how the BPE debugger would proceed through the following code sample:
<A>
<B/>
</A>
<D/>
(A, B, and D are some xml elements)
Table A-7 Example Debugging Process
Execution Order
Result
<A>, <B/>, </A>, <D/>
If you are clicking step-into, the debugger highlights the lines in that execution order.
If you are clicking step-over, the debugger highlights <A>, </A> (skipping B), <D/>
<A>, <D/>, <B/>, </A>
If you are clicking step-over, you will see code lines in the order <A>, <D/>, <B/>, </A>. (Step-over is equivalent to step-into for this case.)
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.
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 from where you launched a form or workflow.
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 A-60 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 A-61 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 A-62 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 A-63 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 A-64 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.
Table A-8 Virtual Thread States
Workflow Activity State
Definition
ready
Identifies an activity that has just been transitioned to. (This state is very temporary, as actions typically start executing immediately after being designated ready.)
executing
Identifies an activity that contains one or more actions that are currently being executed or have yet to run.
This is a logical state, which does not mean that the Java thread is currently executing it. The action currently being executed is the action that is highlighted in the debugger.
pending outbound
Identifies an activity after all actions within an activity have been run, it goes to the pending outbound state. In this state, it awaits an outbound transition to be taken. In the case of an or-split, it is in this state until one transition is taken. In the case of an and-split, it will be in this state until all transitions whose conditions evaluate to true are taken.
inactive
Identifies an activity in which all transitions have been taken.
pending inbound
Identifies a virtual thread whose activity is an and-join. That is, one transition to this virtual thread has occurred, but the process is still waiting for other transitions.
After all transitions have completed, the workflow process subsequently begins executing.
Example 1: Debugging a Workflow and a Rule
The example provided in this section shows 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.
For this example, you perform the following steps:
Step One: Launch 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 A-65 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 A-66 Debugging Halted at Breakpoint
Note the following:
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, the stack frame does provide context about 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>).
- Select Debug > Select Current Line (F5) to re-highlight your current line of execution.
Step Two: Start 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 A-67 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: Step 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 A-68 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: Step 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 A-69 Debugger Transitioning from getFirstName to computeFullName
Step Five: Step 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 A-70 Stepping Into computeFullName Processing
Step Six: Step 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 A-71 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 FormThis section provides an example that shows how to debug a sample workflow containing a manual action and a form.
Use workflow2 from the debugger tutorial files and perform the following steps:
- 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 A-72 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 A-73 Stepping Into Manual Action 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 A-74 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 A-75 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 A-76 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 A-77 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 A-78 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 A-79 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 has the pass name.
Derivation
During Derivation phase of form execution, the form engine iterates over each field and it processes each <Disable> expression.
The form engine also processes the <Derivation> expression, for fields whose <Disable> expressions return false.
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.
