Previous      Contents      Index      Next
Sun Java[TM] System Identity Manager 7.1 Deployment Tools

Chapter 1
Using the Identity Manager IDE

The Identity Manager Integrated Development Environment (Identity Manager IDE) is Java application that enables you to view, customize, and debug Sun Java™ System Identity Manager (Identity Manager) objects in your deployment.

This chapter provides instructions for using the Identity Manager IDE. The information in this chapter is organized as follows:

Overview
Installing the Identity Manager IDE
Working with the Identity Manager IDE Interface
Working with Identity Manager IDE Projects
Managing the Embedded Repository
Working with Repository Objects
Working with XML
Working with the Identity Manager IDE Debugger
Uninstalling Identity Manager IDE from NetBeans
Troubleshooting Identity Manager IDE

---

Overview

The Identity Manager IDE provides a graphical and XML-based view of objects in your environment, and you can use this application to perform the following tasks:

Create projects that are associated with specific repositories
View, create, and edit configuration objects, email templates, forms, generic objects, libraries, rules, workflow processes, and workflow subprocesses
Download objects from and upload objects to the repository
Debug forms, rules, and workflows

The rest of this section provides a general, high-level overview of the Identity Manager IDE.

Major Features

Major features provided by the Identity Manager IDE include:

Integrated Explorer window that allows project, directory-based, or run-time views of a project
Identity Manager IDE projects are integrated with a Configuration Build Environment (CBE)
Action menus for document modification
Custom editors, including:
Object property sheets and graphical value editors for enumerating XML object properties and editing basic object types, XPRESS, and XML objects without typing XML
Drag and drop palette for adding approvals, workflow services, workflow tasks, users, and so forth to XML source without typing XML
Registered waveset.dtd definition file that enables syntax highlighting and auto-completion for XML elements and attributes
Integrated debugger for forms, rules, and workflows
Rule tester for verifying standalone and library rules
Form tester for testing forms in an external browser
Checkout View feature allows you to check out, modify, and check in Identity Manager views (such as a user view).
CVS integration

How Identity Manager IDE Compares to BPE

The Identity Manager IDE is a fully integrated NetBeans plugin that was designed to replace Identity Manager’s Business Process Editor (BPE) application. When compared with the BPE, Identity Manager IDE offers the following advantages:

Provides closer alignment with deployment best practices, including:
Modifying objects outside of the repository
Using common deployment tools such as Ant and CVS
Provides platform support for editors, palette, debugger, and navigation
Reduces open-endedness by providing code completion for XML elements and attributes
Provides contextual information, with integrated tools to facilitate editing

Note	The BPE is still supported for backward compatibility. For information about using the BPE, see Appendix A, "Using the Business Process Editor."

---

Installing the Identity Manager IDE

This section provides instructions for installing and configuring the Identity Manager IDE application.

Note	Identity Manager projects were changed significantly in the version 7.1 release and the version 7.1 .nbm requires JDK 1.5 and NetBeans 5.5. Consequently, you must upgrade any projects created with the version 7.0 .nbm. See Upgrading Version 7.0 Projects for instructions.

Before You Begin

To run the Identity Manager IDE, you must have

NetBeans 5.5 running under JDK 1.5 installed on your local system. You can download NetBeans 5.5 from the following location:

http://www.netbeans.org/

Configurator-level access to Identity Manager.

Note	The default Identity Manager project provides a mail.jar, an activation.jar, and a jms.jar in the custom/WEB-INF/lib directory. These jar files are required by the bundled Tomcat (which is shipped with NetBeans by default). If you are going to use a different target application server, you might need to remove these jar files. Refer to the application server product documentation for specific information about its jar requirements.

Upgrading Version 7.0 Projects

To upgrade from the 7.0 .nbm to the 7.1 .nbm, you must perform the following steps:

Upgrade your JDK installation to JDK 1.5.
Upgrade you current NetBeans installation to NetBeans 5.5.
Install the Identity Manager 7.1 .nbm in your NetBeans 5.5 installation.
Create a new Identity Manager project.

You can now create a regular project or a remote project depending on your needs. See What is a Project? for more information about these project types.

Copy the contents of your old project's objects directory to the src/objects directory of your new project.

Installing the Module

Identity Manager IDE is packaged as a module plug-in that you must register with NetBeans. To install and register the module, perform the following steps:

Start NetBeans 5.5.
From the NetBeans menu bar, select Tools > Update Center.
When the Update Center Wizard displays (Figure 1-1), select Install Manually Downloaded Modules, and then click Next.

Figure 1-1  Selecting the Module Location



In the Select Modules to Install panel (Figure 1-2), click Add to locate and select the Identity Manager IDE NetBeans plug-in file (com-sun-idm-ide.nbm), which file is provided in Identity Manager’s image directory.

Figure 1-2  Specifying the Module to Install



Click Next and the Select Modules to Install panel displays. Click Next again to download the module.
When the Identity Manager IDE License Agreement displays, click Accept.
The Download Modules panel displays to show you the status of the module(s) being downloaded. Click Next.
The View Certificates and Install Modules panel displays (Figure 1-3), containing a list of the module(s) you downloaded. Enable the check box beside the module name.

Figure 1-3  Select the Module to View Its Certificate



A pop-up displays, asking if you really want to install an unsigned module.
Click Yes to continue installing the module.
Click No if you do not want to continue the installation.
Click Finish.

NetBeans installs the Identity Manager IDE module.

You can now

Create Identity Manager projects within NetBeans
Download objects from the Identity Manager installation
Create new XML object files to upload

---

Working with the Identity Manager IDE Interface

The Identity Manager IDE interface (shown in Figure 1-4) consists of an IdM menu (located on the NetBeans' top-level menu bar) and the following windows:

Figure 1-4  Identity Manager IDE User Interface

Note	Not all of these windows display when you first open the Identity Manager IDE, but they will open automatically (or can be opened) as you use different features in the application. You will encounter features (such as menu options) that are part of the NetBeans user interface. These features are not discussed in this publication. Consult the NetBeans online help or product documentation for information about these features.

This section introduces the IdM menu and each of the Identity Manager IDE windows. The information is organized as follows:

IdM Menu
Explorer Window
Editor Window
Palette Window
Properties Window
Output Window
Debugger Windows

IdM Menu

The IdM menu becomes available from NetBeans' top-level menu bar after you have installed and configured the Identity Manager IDE application.

You can use the IdM menu to select actions that are appropriate to whatever nodes are currently selected in the NetBeans Explorer. For example,

If you select a folder, you can upload or download objects.
If you select an Identity Manager XML file, you can upload or reload objects.

Table 1-1 describes all of the IdM menu options.

Tip	Most IdM menu options are also available on a pop-up menu that displays when you right-click objects in the Project tree. Additional information about using these IdM options is provided in the Managing the Embedded Repository, Working with Repository Objects, and Working with the Identity Manager IDE Debugger sections.

Table 1-1  IdM Menu Options  

Select	To Perform the Following Action
Repository > Explore	Open the Explore Repository window so you can browse the contents of the Identity Manager IDE repository. You can select one or more objects and then Click the Download button to download the objects to your local file system. Click the Delete button to remove selected objects from the Repository.
Repository > Open Object	Open an object in the Editor window. Note: You can only open objects on your local file system. If you try to open an object that has not been downloaded from the repository yet, Identity Manager IDE automatically downloads the object to your local file system, and then opens it in the Editor.
Repository > Checkout View	Check out a particular view (such as a user view) from the repository for editing.
Repository > Upload Objects	Upload objects from your local file system to the repository. See (more...) for more information.
Repository > Diff Objects	Compare all objects in a directory on your local file system with their counterparts in the repository. Identity Manager IDE diffs all of the objects in the directory recursively down through the file system and then provides a side-by-side comparison of the Local and Remote XML code with syntax highlighting and line numbers.
Repository > Manage Embedded Repository Note: This menu option is not available for Identity Manager Project (Remote) or if you specify your own repository.	Open the Manage Embedded Repository dialog so you can modify the following repository settings for the current project: Repository Location: Specify a different repository location. Initialize Repository: If enabled, Identity Manager IDE removes existing data files and imports the init.xml file from the idm.war. Do not enable this option if you simply want to change the location of your repository to one that is already initialized. Automatically Publish Identity Manager Objects: If enabled, Identity Manager IDE automatically uploads all Identity Manager objects in the project to the repository every time you run or debug the project.
Repository > Reload Object	Replace (overwrite) an object in the current project with a new version of that object from the repository.
Run LH command	Execute lh commands (such as lh console or lh setup) from within the Identity Manager IDE.
Set Identity Manager Instance	Open the Set Identity Manager Instance dialog, where you can control for which Identity Manager instance the following actions apply in the context of a given project: Debug Project Repository > Explore Repository > Open Project Checkout View Upload Object(s) Diff Object(s) Reload Object Test Form Test Rule For more detailed information, see Setting the Identity Manager Instance.
Clear Credentials Cache	Cause Identity Manager IDE to forget passwords it remembered when users enabled the Remember Password option.
Options	Remove all auto-generated repository IDs that conform to a specified expression — without removing any hard-coded, predefined IDs — before Identity Manager IDE downloads objects from the repository. This feature is useful if you want to move objects from one repository to another. Specify Diff Options by enabling or disabling the Exclude lastModDate, Exclude Ids, or Apply pattern substitution options. See Using the Diff Options for more information about diffing objects.
Test Form	Test forms in a browser.
Test Rule	Verify modifications made to standalone and library rules.

Explorer Window

The Explorer window, located in the upper right corner of the Identity Manager IDE provides three windows:

Projects Window
Files Window
Runtime Window

Projects Window

The Projects window displays in the Explorer by default when you open the Identity Manager IDE, and it provides a vertical, logical view of all open projects.

Expand the project node for a hierarchical view of the XML objects in the project, which includes:

Configuration Objects
Email Templates
Forms
Generic Objects
Libraries
Rules
Workflow Processes
Workflow Subprocesses

Most elements that make up an XML object are also represented by nodes in the project tree.

Note	By default, the object nodes are presented in the same order within the Project tree as they occur in the XML object. However, you can change their order in the tree (and in the XML object) using the Change Order, Insert Before, Insert After, Move Up, or Move Down pop-up menu options. See Table 1-2 for a description of these options.

Figure 1-5 shows various top-level XML files and some variable, library, rule, and argument nodes.

Figure 1-5  Projects Window

When you right-click on any node in this window, a pop-up menu displays with options that enable you to perform different tasks related to that node.

Note	Some of the menu options are provided by the NetBeans application, and are not discussed in this publication. Consult the NetBeans online help or product documentation for information about these options.

Table 1-2 provides an overview of the pop-up menu options that pertain to Identity Manager IDE.

Table 1-2  Identity Manager IDE Pop-Up Menu Options  

Node	Menu Options	Description
Project >	Debug Project	Select to debug the project.
	Close Project	Select to close the project.
	Repository >	Select to explore the repository; open, upload, or diff objects; check out views; or manage the embedded repository.
Object Node >	Add	Select to create a new object for this project.
	CVS	Select to manage CVS versioned-controlled files from within Identity Manager IDE.
	Repository	Select to download objects from the repository to your local file system, upload objects from your local file system to the repository, and to checkout a view.
	Find	Select to search your project for text, object names, object types, and dates. You can search all projects in the Project window, or select and search a specific location.
	Cut, Copy, Paste	Select these options to cut and paste, or copy and paste, objects.
	Delete	Select to delete selected objects from the project.
	Refactor	Select to modify the object’s code structure and update the rest of your code to reflect the modifications.
	Tools	Select to create JUnit tests, add to Favorites, manage Internationalization, or to apply a Diff patch.
	Properties	Select to view and edit the selected object’s properties (such as TaskDefinition Properties, Configuration Properties, and Repository Properties).
	Add element	Select to add actions, arguments, activities, forms, object references, processes, properties, results, returns, rules, transitions, or variables to the object. Note: The object node type determines which elements can be added. For example, you can add arguments, forms, results, returns, and variables to an Action object.
	Change Order	Select to change the order of multiple objects at once. A Change Order dialog displays so you can move multiple objects up or down to change their position in the Project tree and in the XML object.
	Insert Before	Select to move a selected object node above a specified object node in the Projects tree.
	Insert After	Select to move a selected object node below specified object node in the Projects tree.
	Move Up	Select to move a selected object node up the Projects tree.
	Move Down	Select to move a selected object node down the Projects tree.

Files Window

Select the Files window and expand the nodes for a directory-based view of your projects, including files and folders that do not display in the Projects Window.

You can open and edit your project configuration files, such as the project’s build script and the properties files.

Note	When you create a new project, Identity Manager IDE automatically creates a README.txt file. To see a detailed overview of your project’s file system (or if you want to modify the project structure to work with a different Configuration Build Environment (CBE)), double-click README.txt in the Files window and the information displays in the Editor window.

Runtime Window

Select the Runtime window for read-only access to the Identity Manager catalog (waveset.dtd) under the DTD and XML schema catalogs.

Editor Window

The Editor window provides a toolbar and a display area that enable you to work with objects in Design view or Source Editor view.

Design view: Use this view to work with
An Expression Builder to work with Rule objects. (See Design View For Rules for additional information.)
A graphical representation of Workflow Process and Workflow Subprocess objects. (See Design View For Workflows for additional information.)

Note	When you are working with rules and workflows, Design view is the default view.

Source Editor view: Use this view to work with the object’s XML source.
(See Source Editor View for additional information.)

The remaining buttons on the toolbar change, depending which view is selected.

Note	You can drag items from the Palette window into the Editor window. For example: You can drag new Workflow services, approvals, users and Workflow tasks into the Editor for workflows. You can drag new fields into the Editor for forms. Dragging items into Design view, updates the XML source and the node tree in both the Projects and Files views. (See Palette Window for more information.)

Design View For Rules

This section describes the Design view editors for rules and workflows.

The Design view editor for rules provides an Expression Builder (Figure 1-6) that makes it easier for you to see the logical structure of a rule and to modify the rule’s properties.

Figure 1-6  Example Design View for Rules

To open a rule in Design view, double-click the rule in the Projects window or select the rule node, and then click the Design button.

Instructions for using the Expression Builder are provided in Using the Expression Builder Dialog.

Design View For Workflows

The Design view editor for workflows provides a graphical diagram of a workflow (Figure 1-7), where each node represents a specific process activity and the lines represent transitions.

Figure 1-7  Example Workflow Design View

To work with the Design view for workflows, double-click a workflow in the Projects window or select the workflow node and then click the Design button.

In Design view, you can use the toolbar to perform the following tasks:

Table 1-3  Design View Toolbar Buttons

Click this Button		To Perform this Task
	Add Activity:	Click to add activities to the Workflow.
	Remove Activity:	Click to remove one or more Activities from the workflow. (To delete multiple activities, press the Ctrl key while selecting nodes.)
	Layout:	Click to layout the workflow. Resets and organizes activities if they are arranged in a chaotic fashion.
	Validate XML:	Click to validate the workflow. The validation information displays in the Output window, and typically contains hyperlinks that take you to a line in the Source Editor View so you can view or fix the XML.

In addition to these buttons, you can use the Workflow Selector menu (also provided on this toolbar) to select and work on a workflow or workflow subprocess in Design view.

When you edit a workflow in Design view, the Palette window displays items loaded from the workflow library. You can drag these items from the Palette and drop them into Design view to create an activity node in the diagram (which also updates the XML source and the node tree in the Project and Files views). See Palette Window for more information.

Source Editor View

The Source Editor is a full-featured text editor that displays a selected object’s unfiltered XML. In addition, the Source Editor is integrated with the Explorer Projects window and the Debugger.

You can open the Source Editor view by:

Double-clicking an editable object in Projects window
Creating a new, editable object from the available Identity Manager IDE templates (which opens the Source Editor automatically)
Clicking the Source button at the top of the Editor window (only available for Rules and Workflows)

Figure 1-8  Example Source Editor View

Table 1-4 describes the toolbar buttons (from left to right) provided for the Source Editor view. The table also provides keyboard shortcuts for these tasks.

Table 1-4  Source Editor View Toolbar Buttons (and Shortcuts)  

Use this Button	To Perform this Task
	Back (Alt+K) and Forward (Alt+L): Click these buttons to move back to the last edit, or forward to the next edit, you made in the Source Editor window.
	Use these buttons to move the cursor’s insertion point as follows: Find Previous Occurrence (Shift+F3): Click this button to locate and move the insertion point to text that you previously searched for. Find Selection (Ctrl+F3): Click this button to locate the item where your cursor is currently inserted. Find Next Occurrence (F3): Click this button to locate and move the insertion point to the next occurrence of text that you are searching for.
	Use these buttons to toggle the features on or off as follows: Toggle Highlight Search (Alt+Shift+H): Click this button to turn highlighting search text on and off. Toggle Bookmark (Ctrl+F2): Highlight a line and then click this button to insert a bookmark on, or remove a bookmark from, the current line.
	Next Bookmark (F2) and Previous Bookmark (Shift+F2): Click these buttons to locate the next bookmark or previous bookmark in the XML source.
	Next Matching Word (Ctrl+L) and Previous Matching Word (Ctrl+K): Select a word in the XML source, and then click these buttons to locate the next or previous occurrence of that word.
	Shift Line Left (Ctrl+D) and Shift Line Right (Ctrl+T): Click these buttons to reduce or increase the indentation of a selected line by one tab stop.
	Start Macro Recording (Ctrl+J S) and Stop Macro Recording (Ctrl+J E): Click these buttons to start or stop recording a macro containing keystrokes and cursor movements.
	Use these buttons to check or validate your XML source as follows: Check XML (Alt+F9): Click this button to check whether you object’s XML is correct and well-formed. The Output window identifies errors in your XML source, and typically provides a hyperlink to the line in the Source Editor so you can correct the problem. Validate XML (Alt+Shift+F9): Click this button to validate the object’s XML against the dtd. Validation information displays in the Output window, and typically contains hyperlinks to the line in the Source Editor View so you can view or fix the XML.

Setting Breakpoints

You can set breakpoints (distinct stopping points in process execution) in the Source Editor by clicking in the left margin immediately adjacent to an XML tag. For example, if you click in the margin next to the <WFProcess...> tag, you can set a breakpoint at the start of the workflow.

Figure 1-9 shows an example breakpoint.

Figure 1-9  Example Breakpoint

Dragging from the Palette

When you select objects for editing, the Palette window (see (more...) ) automatically displays (typically in the upper right side of the Identity Manager IDE) with items from the workflow library and XPRESS categories. You can drag items from the Palette and drop them into a line in the Source Editor to create XML text at that point in the XML source.

Inserting Invokes

When you right-click in an open XML file in the Source Editor, a pop-up menu displays that provides the following Insert options:

Insert Instance Invoke: Calls an instance method on a Java object that is provided in the first argument. If the invoke does not have a classname attribute defined then it is a instance invoke type.
Insert Static Invoke: Calls a static Java method. If the invoke has a classname attribute defined then it is a static invoke type.

Selecting either option opens a Insert Invoke dialog where you specify

Instance Reference (for Instance Invokes only)
Class Name
Method Name (Your class selection determines which methods are available.)

Tip	Clicking the drop-down arrows on the Class Name and Method Name menus opens JavaDoc for the classes or methods, respectively. As you run the cursor over names in the list, the related JavaDoc displays in a pop-up alongside the dialog.

Figure 1-10 shows an example Insert Invoke dialog with the JavaDoc display.

Figure 1-10  Example Insert Instance Invoke Dialog with JavaDoc

When you click OK, and Identity Manager IDE automatically generates the XML text at that point in the XML source.

Note	When working with Workflow processes or subprocesses, you can add Action expressions to perform simple calculations or call out to Java classes or JavaScript to perform complex operations.

Palette Window

The Palette window (such as Figure 1-11) enables you to “drag-and-drop” elements into Email Template, Form, Library, Workflow Process, or Workflow Subprocess objects displayed in the Editor windows — without having to type XML.

Figure 1-11  Example Palette Window for Delete User Object

For example, you can drag fields into Form objects, rules into Library objects, or workflow services, approvals, users, and workflow tasks into Workflow Process and Workflow Subprocess objects.

When you double-click objects in the Project tree, the Palette window displays (typically in the upper right side of the Identity Manager IDE) and provides access to different elements — depending on the editing view, as follows:

Design view provides a graphical representation of items loaded from the workflow library. Dragging items from the Palette into Design view creates an activity node in the diagram.
Source Editor view displays the XML source of items loaded from the workflow library and XPRESS categories. Dragging items from the Palette into the Source Editor creates XML text wherever you drop the item in the XML source.

Dragging items into either Editor window updates both the XML source and the node tree in the Projects and Files views.

Note	After adding elements to an object, you can change the order of those elements in the Project tree and in the XML object using a variety of pop-up menu options. See Table 1-2 for a description of the Change Order, Insert Before, Insert After, Move Up, and Move Down options.

Properties Window

The Identity Manager IDE Properties window consists of a properties sheet for XML elements associated with Email Template, Form, Library, Rule, Workflow Process, and Workflow Subprocess objects. You can use this properties sheet to view and edit a selected object’s properties; including the object name, file sizes, modification times, result information, and so forth.

Use one of the following methods to open the Properties window:

Select Window > Properties from the main menu bar
Right-click a node in the Projects window and select Properties from the menu.

When the Properties window is open, you can double-click an object node to update the contents of the window.

Figure 1-12  Example Properties Window

Note	Instructions for using properties sheets to modify an object’s XML elements are provided in Editing Objects.

Tip	As an alternative to the using Properties window, right-click object nodes in the tree and select Properties from the pop-up menu. A Properties dialog displays with the same object property sheet you would see in the Properties window.

Output Window

The Output window displays messages from the Identity Manager IDE when it finds errors during debugging. These messages usually include hyperlinks to the lines in your source code that caused the errors.

The Output window opens automatically when you run the Debugger, or you can open this window by selecting Window > Output from the main menu bar.

Figure 1-13  Example Output Window

Debugger Windows

The Identity Manager IDE Debugger is similar to both the Java Debugger and the Debugger provided with the BPE — you can set line, global, view, or form cycle breakpoints in the code, start the Debugger, and have the code stop in the XML.

In addition, the Identity Manager IDE Debugger is integrated with a rule tester and form tester, and it enables you to add a watch to show the value of a particular variable. (These features are discussed later in this chapter.)

The Debugger provides the following windows to help you troubleshoot your XML source:

Breakpoints Window
Call Stack Window
Local Variables Window
Watches Window

Breakpoints Window

Breakpoints window lists all of the breakpoints you have set for the current project, including a short description of the breakpoint and a boolean flag that indicates whether the breakpoint is currently enabled or disabled.

Select Window > Debugging > Breakpoints from the main menu bar to open the Breakpoints window.

Figure 1-14  Example Breakpoints Window

You can enable or disable a breakpoint by changing its Enabled property in the Breakpoints window.

Call Stack Window

The Identity Manager IDE automatically launches the Call Stack window when you run the Debugger.

When the Debugger reaches a breakpoint, the execution stack (a series of calls that the thread performed to get to the breakpoint) displays in the Call Stack window. In XPRESS, these calls are XPRESS operations such as BLOCK or CASE.

If additional functions appear in the call chain, these functions are listed in order. This list is called a stack trace, and it displays the structure of the execution stack at this point in the program's life.

Note	If you close the Call Stack window (or it is unavailable for another reason) you can re-open the window by selecting Window > Debugging> Call Stack from the main menu bar.

Local Variables Window

The Local Variables window lists all variables that are in scope at the current point of execution when the Debugger stops at a breakpoint. Variables represent values of the following types:

Simple (such as strings)
Complex, which contain other values (such as lists and maps)

You can expand complex types to show their contained elements.

The Local Variables window remains blank when debugging is inactive or when execution is not stopped at a breakpoint.

If the current element is an XPRESS end tag, the result of the last evaluation displays in the Local Variables window when you stop the Debugger. This evaluation value also applies to other tags for which last value makes sense. For example, as Identity Manager evaluates <Argument> tags to workflow subprocesses, the argument value shows in the Local Variables window.

Note	The Local Variables window does not display variables while XPRESS execution is in progress. The Last Value entry remains blank when debugging is inactive.

Watches Window

The Debugger allows you to use watches, which enable you to track changes made to variable or expression values when you run the Debugger. A watch can be any valid XPRESS expression.

When you specify a watch, the Watches window lists all of the variables, expressions, types, and values that are being watched when you debug the project. This list may also contain hyperlinks to take you to the object type in the XML source.

The Identity Manager IDE automatically launches the Watches window when you run the Debugger (or you can select Window > Debugging > Watches from the main menu bar).

Using Keyboard Shortcuts

Through NetBeans, Identity Manager IDE enables you to use different keyboard combinations to run commands and navigate in the Identity Manager IDE, including:

Menu shortcuts help you navigate, activate, and select menu options from the menu bar.
Source Editor shortcuts help you execute commands and actions in the Editor. Some of these shortcuts are common to all file types, while others are only available when editing certain file types.
Window shortcuts help you navigate, activate, and select operations in the Identity Manager IDE windows.
Help shortcuts help you navigate the Identity Manager IDE Online Help System.

For a detailed description of available keyboard shortcuts and instructions for using them, refer to the online help.

Note	To assign shortcuts, select Tools > Options, and when the Options dialog displays, select Keymap.

---

Working with Identity Manager IDE Projects

To use Identity Manager IDE effectively, you must also understand some basic concepts about the Identity Manager IDE project. This section provides the following information:

What is a Project?
Creating a Project
Choosing an Existing Project
Setting the Identity Manager Instance

What is a Project?

A project is a collection of source files (JSPs, Java, and Identity Manager objects), build scripts, and so forth that control all of the customizations for a deployment.

Projects are tied to a specific repository. You can associate more than one project with a repository, but only one repository per project.

Note	Identity Manager IDE projects allow you to interact directly with CVS. Refer to your NetBeans documentation for information.

You can create one of the following project types for Identity Manager IDE:

Identity Manager Project: Fully featured project provided as the primary development environment for deployers. Highlights include:
Full build environment
Ability to manage custom Java code and JSPs
Integrated with NetBeans embedded application server to allow local deployment of the Identity Manager war file
Integrated Java, JSP, workflow, form, and XPRESS debugging
Embedded database repository
Identity Manager Project (Remote): Less-featured project for making small modifications and debugging on an external server. This project has all the editing functionality of the full-blown Identity Manager project, but lacks the build environment and ability to launch the war.

Creating a Project

To create a new project, use the following steps:

Select File > New Project.
When the New Project wizard displays (Figure 1-15), select Web from the Categories list to indicate what type of project you are creating.

Figure 1-15  New Project Wizard: Specify a Category



Select one of the following sample Identity Manager projects from the Projects list:
Identity Manager Project: Select this project for a fully featured development environment, which includes:
A sample Configuration Build Environment (CBE)
The ability to manage custom Java code and JSPs
Integration with the NetBeans embedded application server, which allows you to deploy the Identity Manager war locally
Integrated Java, JSP, workflow, form, and XPRESS debugging
An embedded database repository
Identity Manager Project (Remote): Select this project to make small modifications and to perform debugging on an external server.

This project type has all of the editing functions as the full Identity Manager project, but it does not provide the build environment or give you the ability to launch the Identity Manager.war file (idm.war).

When you are finished, click Next.
If you selected the full project, continue to the section titled, Creating the Identity Manager Project.
If you selected the Remote project, continue to the section titled, Creating the Identity Manager Project (Remote).

The Identity Manager IDE now works with different versions of the server.

Each Identity Manager IDE project is tied to a specific Identity Manager version, and the Identity Manager IDE requires a compatibility bundle (a zip file that provides Identity Manager jar files and some XML registries containing version-specific information for each supported Identity Manager version.

For Identity Manager Projects: The compatibility bundle is included in the idm.war file, and Identity Manager IDE automatically accesses this file during project setup.
For Identity Manager Projects (Remote): Because you do not specify a war file location for remote projects, you must provide the compatibility bundle’s location, which is:

<Identity Manager install root>/sample/ide-bundle.zip

Note	Currently, you cannot manage multiple Identity Manager versions from the same project. If you want to perform simple debugging or make simple adjustments to a server for a different version, create a separate remote project (as described on (more...) ) for that server. You also cannot use the Identity Manager IDE to upgrade your existing projects to a newer version. You must perform this task manually, as follows: Shutdown NetBeans. Manually upgrade all of your objects, custom JSPs, and the contents of your project's idm-staging directory. Replace the existing nbproject/ide-bundle.zip with that from the version to which you are upgrading.

Creating the Identity Manager Project

To finish creating the full project, perform the following steps:

The Name and Location panel displays with a default project name, location, and folder in which to store the Identity Manager project.
If the default location is satisfactory, click Next.
If you want to specify a different location, replace the default information and then click Next.

Figure 1-16  New Project Wizard: Specifying Where to Store the Project



When the Identity Manager WAR File Location screen displays, specify the path to the Identity Manager idm.war file, and then click Next.

Figure 1-17  New Project Wizard: Specifying the WAR File Location



When the Repository Setup screen displays, (Figure 1-18) select one of the following options for configuring a repository:
If you want Identity Manager IDE to create an embedded repository, enable the Create Embedded Repository option, and continue with Step 4.

Note	When you select Create Embedded Repository, Identity Manager IDE creates an embedded repository for the default sandbox CBE target. If you specify additional targets, you must also select Manage Embedded Repository or you must run the lh setup or setRepo commands for the additional targets.

If you want to reuse an existing repository from another project, enable the Skip Repository Setup option, and continue with the instructions provided in Configuring a Repository Manually.

Figure 1-18  New Project Wizard: Repository Setup



Specify a directory for the embedded repository data files.
Enable Initialize Repository to remove existing data files and import the init.xml file from the idm.war.

Note	Be sure to disable this option if you want to reuse a repository from another project.

Enable Automatically Publish Identity Manager Objects to automatically publish all Identity Manager objects in the project to the repository every time you Run or Debug the project.

Note	This option is not available for Identity Manager Project (Remote) or if you specify your own repository.

Click Finish.

A Creating Project dialog displays while Identity Manager IDE sets up the repository. This process will take some time as Identity Manager IDE removes data files and imports the init.xml file.

The setup is complete when the dialog closes and you see a BUILD SUCCESSFUL message display in the Identity Manager IDE Output window.

You can select the Files tab in the Explorer window and expand the top-level node to view the files associated with your new project.

Note	When you create a new project, Identity Manager IDE automatically creates a README.txt file. To see a detailed overview of your project’s file system (or if you want to modify the project structure to work with a different CBE), double-click README.txt in the Files window and the information displays in the Editor window.

Configuring a Repository Manually

You can configure your project to use any of the repository types supported by Identity Manager.

Note	Manually configuring a repository impacts the repository for the currently selected CBE target. For more information, see Setting the Identity Manager Instance.

Because configuration instructions vary for each repository type — the following example is provided to illustrate the process:

To configure a MySQL repository, perform the following steps:

Copy mysqljdbc.jar into your project's custom/WEB-INF/lib directory.
In the Identity Manager IDE Project window, right-click on the project name and select Run LH Command from the pop-up menu.
When the Enter LH Command to Run dialog displays, type setup into the LH Command field, and then click OK.

The Input field displays below the Output window and the Sun Setup Wizard displays with some introductory information.

After reading the information, click Next.
When the Locate the Repository screen displays, provide the following information and then click Next:
Select the repository type from the menu.
Verify the URL, JDBC Driver, and connection information and modify if necessary.
The Setup Demo? screen displays, asking if you want to continue setting up a demonstration environment. Click No, I will configure Identity Manager myself, and then click Next.
When the Save Configuration screen displays, click Execute to import the init.xml file and save the Identity Manager configuration.
When the import is finished, click Done.

Creating the Identity Manager Project (Remote)

To finish creating a remote project, perform the following steps:

The Name and Location panel displays with a default project name, location, and folder in which to store the Identity Manager project.
If the default location is satisfactory, click Next.
If you want to specify a different location, replace the default information and then click Next.

Figure 1-19  New Project Wizard: Specifying Where to Store the Project



The Identity Manager IDE Compatibility Bundle File Location screen displays.

Note	Because Identity Manager IDE can work with different versions of the server, and every Identity Manager IDE project is tied to a specific Identity Manager version, you must specify an IDE compatibility bundle (a zip file that provides Identity Manager jar files and some XML registries that contain version-specific information) for each supported Identity Manager version.

Specify the location of the IDE Compatibility Bundle for the version of the server to which you are connecting, and then click Next.

For remote projects, the IDE Compatibility Bundle File is located in <Identity Manager install root>/sample/ide-bundle.zip.

Figure 1-20  New Project Wizard: Specifying the IDE Compatibility Bundle
File Location



When the Identity Manager Server Settings screen displays (Figure 1-21), enter the following information to define how you are going to connect to the Identity Manager instance for development, and then click Finish.

Note	Identity Manager IDE supports remote (SOAP) connections. When you set up a remote connection, Identity Manager IDE uses this connection to upload or download objects.

Host: Enter the name of the host where your project is running.
Port: Enter the number of the TCP port on which the directory server is listening.

Enable the Secure Connection box if you want Identity Manager IDE to use SSL when opening the connection.

Context Path: Enter the context root for your Identity Manager installation (for example, /idm)
User: Enter your administrator user name.
Password: Enter your administrator password.

Enable the Remember Password box if you want Identity Manager IDE to remember and automatically enter your password for future sessions.

Figure 1-21  New Project Wizard: Specifying the Server Settings



Click Finish.
If the connection to your remote server is successful, the project node displays in the Identity Manager IDE Projects window (upper left corner).
If the connection fails, an error message displays in the wizard window to provide information about the failure. Correct the problem and click Finish again.

Tip	Remember that you are not connecting to the embedded server. If you experience a connection failure, verify that your remote server is running. You can also test connections in Identity Manager IDE when you edit an existing project’s properties.

Choosing an Existing Project

To open an existing project, use the following steps:

Select File > Open Project.
When the Open Project dialog displays (Figure 1-22), browse to the project folder you want to use and click Open Project Folder.

Figure 1-22  Open Project Dialog



If you already have one or more projects open, the Open as Main Project check box (upper right corner) becomes active.

Enable this box if you want to specify this project as the main project.
Click Open Project Folder and the selected project is added to the Explorer window.

Setting the Identity Manager Instance

You use the Set Identity Manager Instance feature to control for which Identity Manager instance the following actions apply, in the context of a given project:

Debug Project
Repository > Explore
Repository > Open Project
Checkout View
Upload Object(s)
Diff Object(s)
Reload Object
Test Form
Test Rule

Use one of the following methods to open the Set Identity Manager Instance dialog (Figure 1-23):

From the NetBeans main menu bar, select IdM > Set Identity Manager Instance.
From the Projects window, right-click the project node and select Set Identity Manager Instance from the pop-up menu.

Figure 1-23  Set Identity Manager Instance Dialog

Reviewing Project Connection Settings

To view a project’s external connection settings, enable one of the following Identity Manager Instance options:

Embedded (not available for remote projects): Applies all of the following actions to the NetBeans embedded application server:
Checkout View
Debug Project
Diff Object(s)
Reload Object
Repository > Explore
Repository > Open Project
Test Form
Test Rule
Upload Object(s)
External: Applies all of the preceding actions to the server specified by the external connection settings.

Setting the Current CBE Target

To specify the current CBE target for all build actions (Build Project, Run Project, and Debug Project),

Select a target from the Current CBE Target menu.

Note	The selected target also controls which repository is used or set by specifying %%CUSTOM_SERVER_REPOSITORY%% in each of the *-target.properties files. For example, if you set the CBE target to dev and select IdM > Repository > Manage Embedded Repository (or you select IdM > Run LH Command and enter setRepo or setup) Identity Manager IDE looks in dev-target.properties to get %%CUSTOM_SERVER_REPOSITORY%%, which is nbproject/private/dev-ServerRepository.xml. Identity Manager IDE then sets nbproject/private/dev-ServerRepository.xml to the specified repository. When you perform a Build Project action, the generated war file contains a ServerRepository.xml equal to nbproject/private/dev-ServerRepository.xml. When you perform a Run Project or Debug Project action, Identity Manager IDE launches the war file in NetBean’s embedded application server with a server repository equal to nbproject/private/dev-ServerRepository.xml.

Enable the Apply Pattern Substitutions on File Upload box if you want the Identity Manager IDE to apply the pattern substitutions defined in <target-name>.properties whenever you upload one or more files to the repository. (Where target-name is the target selected by Current CBE Target.)

To verify how this feature works with multiple targets, create two targets with two different repositories, as follows:

Create a new (full-featured) Identity Manager project and, when the Repository Setup screen displays, select Create Embedded Repository.
Click Finish to create the repository and to set the current target to sandbox.
Launch the application server.

From the Projects tab, right-click the project node and select Run Project from the menu.

When the Identity Manager browser opens, log in and create a user named sandbox-user.

After creating the account, select the List Accounts tab and you should see sandbox-user listed.

Shutdown the application server.

From the Identity Manager IDE Runtime tab, expand the Servers node, right-click Bundled Tomcat, and then select Stop from the pop-up menu.

Once the server has stopped, return to Identity Manager IDE Projects tab, right-click the project node, and select Set Identity Manager Instance.
When the Set Identity Manager Instance dialog displays, change the Current CBE Target to dev, and then click OK.
When you are prompted to clean the project, select Yes.
Next, create a repository for the dev target.
Right-click the project node and select Repository > Manage Embedded Repository from the menu.
Specify a different location for the dev target than the one used for the first repository.
Enable the Initialize Repository option, and then click OK.
When you see the BUILD SUCCESSFUL message in the Output window, right-click the project node and select Run Project.

Notice that the NetBeans log states it is Preparing image for environment target: dev.

Log in to Identity Manager and create a new user named dev-user.

Now, when you select the List Accounts tab, the new dev-user should be listed, but the sandbox-user is not.

Switch back to the sandbox target.
Shut down the server.
Right-click the project node, select Set Identity Manager Instance > Current Target > sandbox.
When you are prompted to clean the project, select Yes.
Right-click the project node and select Run from the menu.
Log into Identity Manager, select List Accounts, and notice that sandbox-user is now available.

---

Managing the Embedded Repository

You can modify the following repository settings for the current project by selecting IdM > Repository > Manage Embedded Repository:

Note	Managing the Embedded Repository will impact the repository for the currently selected CBE target. For more information, see Setting the Identity Manager Instance.

Repository Location: Specify a different repository location.
Initialize Repository: If enabled, Identity Manager IDE removes existing data files and imports the init.xml file from the idm.war.

Disable this option if you want to reuse a repository from an existing project.

Automatically Publish Identity Manager Objects: If enabled, Identity Manager IDE automatically uploads all Identity Manager objects in the project to the repository every time you run or debug the project.

Note	This option is not available for Identity Manager Project (Remote) or if you specify your own repository.

---

Working with Repository Objects

Identity Manager IDE enables you to work with repository objects on your local file system, rather than working directly in the repository (as with the BPE).

This section provides the following information:

Supported Object Types
Checking-Out Views
Getting Objects from the Repository
Uploading Objects to the Repository
Creating New Objects
Editing Objects
Using the Diff Options

Supported Object Types

You can work with the following object types in the Identity Manager IDE:

Configuration Object: A persistent object that contains forms and workflow processes.
Email Template: Templates used to send notification of various changes and actions to users and administrators. You might use an email template, for example, to notify an approver of a pending request, or to notify a user that his password has been reset.
Form: An object associated with a Web page that contains rules about how a browser should display user view attributes on that page. Forms can incorporate business logic, and often are used to manipulate view data before it is presented to the user.
Generic Object: An object typically used to represent views, such as simple collections of name/value pairs. Generic objects have an <Extension> of type <Object>.
Library: An object used to organize closely related objects, typically rules, into a single object in the repository. Organizing objects into libraries makes it easier for workflow and form designers to identity useful objects.
MetaView: In Identity Manager, a meta view is a unified view of all resources, providing a common data model in which to view a set of resources and how attributes on these resources flow from one to another.
Rule: Objects in the Identity Manager repository that contain functions written in the XPRESS, XML Object, or JavaScript languages. Within Identity Manager, rules store frequently used logic or static variables for reuse in forms, workflows, and roles.
Workflow Process: A workflow is a logical, repeatable process during which documents, information, or tasks are passed from one participant to another. Identity Manager workflows comprise multiple processes that control user accounts, such as account creation, update, enabling, disabling, and deletion.
Workflow Subprocess: An object used to create a workflow subprocess to include in a workflow.

Checking-Out Views

The Identity Manager IDE allows you to check out a particular view (such as a user view) from the repository for editing.

Note	In general, do not use the Checkout View feature to update a user. This feature is provided only to help you understand view behavior. To update users in Identity Manager, use the Identity Manager Web interface.

To check out a view,

Right-click Custom Identity Manager Objects folder in the Project window and select Repository > Checkout View from the pop-up menu.
When the Checkout View dialog displays, select a View type from the menu, enter View name, and then click OK.

Identity Manager IDE opens the view contents in tree format.

After editing, right-click on the view to check it back into the repository — just like any other XML object.

Getting Objects from the Repository

One advantage to using the Identity Manager IDE, is that it enables you to download and modify objects outside of the repository. You can also, if necessary, reload an object from the repository to replace one you modified on your local file system.

This section describes the different methods for getting objects from the repository, including:

Downloading Objects
Opening Objects
Reloading Objects

Downloading Objects

To download an object from the repository to your local files system for the first time, use the following steps:

Right-click the Custom Identity Manager Objects node and select Repository > Explore to open the Explore Repository dialog displays (Figure 1-24).

Figure 1-24  Explore Repository Dialog



Expand the nodes to browse the objects in the Repository, and select the object you want to download from the tree.

Tip	You can download multiple objects from the repository by pressing the Ctrl key as you select the objects from the list.

Click Download.

Identity Manager IDE adds the selected object node, and children that represent individual elements in the object, to the Custom Identity Manager Objects tree in the Explorer. Double-click the child nodes to view their XML elements in the Editor and to view their properties sheet in the Properties window.

Opening Objects

If you already know the name of an object you want to open on your local file system, use the Open Objects option to quickly locate and download a single object from within a larger set of objects (such as the repository).

To use the Open Objects option,

Select IdM > Repository > Open Object from the IdM menu (or right-click the Custom Identity Manager Objects node and select Open Object).

When the Open dialog displays.

Use the options on this dialog to specify your object search criteria:
Object Type: Select object types for which to search.

Note	Common Configuration Object Types is the default selection, which enables you to search for any of the configuration objects loaded within the system by default (Configuration, Email Template, Form, Generic Object, Library, Rule, Workflow Process, and Workflow Subprocess). Generally, you do not have to change the Object Type unless you want to search for a different object type or your search results exceed the maximum number of results.

Object Name: Type all or part of the object name into the text field.

You can specify an asterisk (*) as the object name to access all objects of a particular type in the repository.

As you begin typing the object name, a list of matching items displays in the Matching Objects field. Each new letter narrows the displayed results. For example, if you type Creat (for Create User), a large number of results display (for example see Figure 1-25).

As you type more of the entry, such as Create, the results narrow because the criteria becomes more specific.

Figure 1-25  Open Object Dialog



Case Sensitive: Enable this box to constrain the search to object names that match the case used in the Object Name field.
Select the object you want to open in the Matching Objects list, and then click Open (or press the Enter key) to open that object in the Identity Manager IDE.

Note	The Matching Objects list can return a maximum of 1000 objects. If your search results exceed this number, a message displays to suggest you refine the search criteria. If you try to open an object that has not been downloaded from the repository yet, Identity Manager IDE automatically downloads the object to your local file system, and then opens it in the Editor.

Opening Object References

You can right-click nodes in the Project tree to open objects to which certain references refer (such as ObjectRefs, FormRefs, FieldRefs and Workflow Subprocesses). When you right-click an object node representing the object in the tree, you can select Open object name (where object name is Reference, Form, Field, or External Process respectively) from the pop-up menu.

If the object to which the reference refers exists on your local file system, the Identity Manager IDE opens the source code from the local file system in the Source Editor.
If source code for the object does not yet exist on your local file system, the Identity Manager IDE retrieves the object from the repository and then opens the source code in the Source Editor.

For example, to add a Default User Library object reference to the Tabbed User Form:

Download the Tabbed User Form and expand the nodes until you see the Includes node.
Right-click the Includes node and select Add an Object Reference.

The object reference does not yet exist on your local file system, so the Add Object Reference dialog displays.

You can browse and select an object or type the object name directly into the Name field. Select the Default User Library object, and then click OK to add the new object under the Includes node in the tree.
Now, when you right-click the new Default User Library object reference node and select Open Reference, the Identity Manager IDE downloads the Default User Library object reference form and opens the XML source in the Source Editor.
Close the object reference form in the Source Editor.
Right-click the object reference node again and open the Default User Library reference.

The Default User Library form opens in the Source Editor, but it is not downloaded because it now exists on your local file system.

Reloading Objects

To replace (overwrite) an object in the current project with a new version of that object from the repository, use the following steps:

Right-click the object node and when the pop-up menu displays, select Repository > Reload Objects.

Tip	You can download multiple objects from the repository by pressing the Ctrl key as you select the objects from the list.

An Overwrite Files? dialog displays to let you know that the object already exists on your local file system, and asking you to confirm that you want a fresh copy from the repository.
Click Yes or Yes for All to continue.
Click No or No for All if you do not want to proceed.
When you are ready, click the Reload button.

The selected object nodes, and children that represent individual elements in the object, will be displayed in the Explorer. You can double-click child nodes to go to their XML elements and view them in the property sheet.

Removing Object IDs

To facilitate moving objects from one repository to another, you can configure Identity Manager IDE to remove all auto-generated repository IDs before it downloads objects from the repository.

Note	In general, you should not have to modify the regular expression pattern; the default should be sufficient. This feature is provided in case the default pattern is broken.

Identity Manager IDE locates and removes all object IDs and objectRef IDs that conform to a specified expression — without removing any hard-coded, predefined IDs.

To configure this feature,

Select IdM > Options to open the Repository Options dialog.
Enter a regular expression in the ID Removal Pattern field, and then enable the Use ID Removal box.

Note	The Use ID Removal box is enabled by default. Identity Manager IDE stores the regular expression and displays the most recently used expression in the ID Removal Pattern field by default, which allows you to quickly reuse expressions you used previously.

Uploading Objects to the Repository

To upload new or modified objects from your local file system back to the repository, use the following steps:

Select the one or more object nodes in the Projects window.

Tip	You can select multiple objects to upload by pressing the Ctrl key as you select the objects from the list.

Right-click a node and select Repository > Upload objects from the pop-menu.

Identity Manager IDE immediately uploads the selected objects.

Uploading Objects Automatically

When you create a new project, you can enable a Automatically Publish Identity Manager Objects option and Identity Manager IDE will automatically upload all Identity Manager objects to the repository whenever you run or debug the project.

See Creating the Identity Manager Project for instructions.

You can enable this option after project creation from the Manage Embedded Repository dialog (IdM > Repository > Manage Embedded Repository).

Note	This option is not available for Identity Manager Project (Remote) or if you specify your own repository.

Using CBE Pattern Substitution

Identity Manager IDE allows you to use a CBE (Configuration Build Environment) pattern substitution file when uploading objects to an embedded or external Identity Manager instance.

When you select IdM > Set Identity Manager Instance from the main menu bar, the Set Identity Manager Instance dialog displays. If you enable Apply Pattern Substitutions on File Upload, the pattern substitutions defined in target-name.properties (where target-name is the target selected by Current CBE Target) will be applied whenever you upload one or more objects.

For example, sandbox-target.properties is the default target and it defines %%SMTP_HOST%%=mail.xyzcompany.com. Users can replace mail.xyzcompany.com in sandbox-target.properties with the name of their SMTP server, and then use the %%SMTP_HOST%% variable in the Identity Manager object files as appropriate.

Note	The Identity Manager Project provides a sample CBE and the nbm is aware of the CBE pattern substitution files. The *-target.properties files are also used by the CBE build and the publishIDMObjects ant target. You can move the *-target.properties files to a different directory, but you must update the build.xml and the cbeConfigDir attribute in idm-project.xml to account for this change.

Creating New Objects

To create a new object for your project, use the following steps:

Right-click an object node (or an object types node) in the Projects window and select New > File/File Folder.
In the New File wizard, select the Sun Identity Manager Objects category, and then select an object type to create. Click Next.
In the Name and Location screen, enter a file name and specify where to store the file.

Note	The current project, project directory, and objects folder are selected by default, but you can specify a different location.

Click Finish to close the wizard.

Identity Manager IDE adds the new object to the tree as a child under the selected object type node. In addition, the new object’s XML source is displayed in the Source Editor view.

Note	Identity Manager IDE assumes that each XML source file contains exactly one object. Consequently, if you use XML files containing multiple objects (including some files distributed with Identity Manager, such the wfresource.xml sample), the objects do not display as nodes in the Project window and they are not available in the Palette. In addition, the context menu does not include any Identity Manager IDE actions. However, if you put these XML files into your project’s Objects directory, Identity Manager IDE handles the files as plain text so you can view the files in the Files tree, and you can open and edit the files directly.

Editing Objects

This section explains how to edit the objects in your project. This information includes:

Editing Object Properties
Adding Elements to an Object

Editing Object Properties

You can modify properties for Email Template, Form, Library, and Workflow objects from the Identity Manager IDE Properties window.

For example, click the Account Deletion Approval object node and following properties sheet (Figure 1-26) displays in the Properties window:

Figure 1-26  Example Properties

Tip	As an alternative to the using Properties window, right-click the object node and select Properties from the pop-up menu. A Properties dialog displays with the same object property sheet you would see in the Properties window.

Properties sheets contain some or all of the following features:

Text fields: Allow you to edit simple or complex values, as follows.
Simple value fields: Type new string or integer values directly into the text field. After modifying or adding a new value,
Press the Enter key (or click in a different text field) to apply your changes.
Press the Esc key to cancel your changes.
Complex value fields: Click the existing value to open a Expression Builder dialog (see Using the Expression Builder Dialog) so you can edit the expression.

Note	Greyed text indicates a read-only field.

Ellipsis (...) buttons: Provide an alternative method for editing object values shown in a text field.
Simple value fields: Clicking the button opens a dialog so you can enter new string or integer values. After modifying or adding a new value,
Click OK to apply your changes and close the dialog.
Click Cancel to undo your changes and close the dialog.
Complex value fields: Clicking the button opens an Expression Builder dialog so you can edit the expression.

Note	Greyed text indicates a read-only field.

Drop-down menus: Select from a list of several, specific values or double-click the property name to rotate through the available values.
Check boxes: Click to enable or disable the property.

Using the Expression Builder Dialog

When you are working in the Properties window, you can click a Complex value field or click the ellipses button to open an Expression Builder dialog (such as those shown in Figure 1-27) to edit an object’s XML expressions.

Figure 1-27  Two Example Expression Builder Dialogs

Expression Builder dialogs consist of

A tree view pane that provides a hierarchical view of the object’s XML expressions.

You can also right-click elements in this view to access options for editing expressions.

An editing options pane that provides a set of editing options for the selected expression element.
An information pane (located at the bottom of most editing options panes) that provides general and JavaDoc information related to the selected expression.

Note	The Design view for rules also provides an Expression Builder (see Figure 1-6) to make it easier for you to see the logical structure of a rule and to modify the rule’s properties.

Table 1-5 describes the different editing options:

Note	For more information about the expression types mentioned in this table, see Identity Manager Workflows, Forms, and Views.

Table 1-5  Expression Builder Options  

Editing Options	Description
Add button Add menu option (only available by right-clicking elements in Tree view.)	Add a new expression element by selecting one of the following expression types: XPRESS Object > Select String, List, Map, or Integer. Reference Expression > Select Logical > Logical type, Strings > String type, Lists > List type, Variables > Define a variable, Math > Math type, Control > Control type. Object Access > Select New, Invoke (Static or Instance), or Get. Diagnostics > Select Script, Trace, or Print. Rule XML Object > Select String, List, Map, or Integer.
Delete button Delete menu option (right-click elements in Tree view.)	Delete the selected expression.
Move Up/Move Down buttons	Move elements up or down within the XML expression.
Wrap Object option (only available by right-clicking elements in Tree view.)	Wrap an expression element (such as a string) within another expression element (such as a concat). This option is useful if you forget to include a function call that needs arguments you already have defined. For example, if you define a reference to the firstname attribute and wrap that reference in a concat, you can then define a reference to the secondname attribute as an argument to the concat — resulting in the following: <concat>    <ref>firstname</ref>    <ref>secondname</ref> </concat>
Change To button Change To menu option (right-click elements in Tree view.)	Change an element’s expression type to one of the following: XPRESS Object > Select String, List, Map, or Integer. Reference Expression > Select Logical > Logical type, Strings > String type, Lists > List type, Variables > Define a variable, Math > Math type, Control > Control type. Object Access > Select New, Invoke (Static or Instance), or Get. Diagnostics > Select Script, Trace, or Print. Rule XML Object > Select String, List, Map, or Integer.
Arrow buttons	Move between recently visited expression-editing panels (similar to a browser’s back and forward buttons).
Type/Value table	View and edit the expression types currently used in the selected expression: Type column (read-only): Lists the expression types. Value column (editable): Lists the expression type values. To edit simple strings or integers, type a new value into the Value field. To edit a <Complex Value>, click the field to open the Expression Builder dialog for that expression.
Style buttons	Set the expression style to Simple or Calculated.
Value fields and <> Name fields	Replace the current simple string or integer.
Trace box	Output trace diagnostics while XPRESS is running inside IDM
Browse JavaDoc button	View JavaDoc information when you are creating invoke expressions. Click this button to open the JavaDoc dialog where you can select items from Class Names and Method Names menus. As you click (or mouse over) a menu item, a pop-up displays the related JavaDoc information.

To edit an expression,

Select an element in tree view, and then use the different options on the editing options pane.

Some editing options (such as the Change To button) are common to most expression elements, while others are only available when you are editing specific elements.

Right-click an element in tree view, and then select an option from the pop-up menu.

Adding Elements to an Object

You can add new (child) elements to objects by editing the XML source directly or using the pop-up menu’s Add option.

Note	You can use the Properties Window to edit object properties, but you cannot use it to add elements.

To use the Add option,

Right-click the object node where you want to add the child element, and select Add element_type from the pop-up menu.

Figure 1-28  Adding Elements to an Action



Note	The object type determines which element_types can be added. For example, if you are working with Workflow processes or subprocesses, you can add Actions to perform simple calculations or call out to Java classes and JavaScript to perform complex operations. You can then add arguments, forms, results, returns, or variables to the Action object.

When the Add element_type dialog displays, use the property sheet to specify a name and other properties for the new element (see Editing Object Properties).

For example, if you are adding a Result to an Action object, the Add Result dialog displays.

Figure 1-29  Add Result Dialog



When you click OK, the Identity Manager IDE adds the new element under the selected object node. In addition, the new element’s XML source is displayed in the Source Editor view.

Note	When adding an Include element to a form, you can either browse for and select the form name or you can type the name directly. When typing a form name, you must use the following syntax or an error (Error creating Object Reference) will result: <FormType>:<SomeFormName> For example, to add the AIX User Form to the Default User Form 1. Download the Default User Form.xml, and expand the tree until you see the Includes node. 2. Right-click the Includes node and select Add Object Reference. 3. When the Add Object Reference dialog displays, you can either type the AIX User Form into the Name field or click Browse to locate and select the form. 4. If typing the name, you must enter UserForm:AIX User Form.

Deleting Objects

To remove objects from the project on your local file system,

Right-click on one or more objects in the Project window.
Select Delete from the pop-up menu.

The objects are immediately deleted from your project.

To remove objects from the Identity Manager IDE repository:

Select IdM > Repository > Explore from the NetBeans menu bar.
When the Explore window displays, expand the object nodes to locate the objects you want to remove.
Select one or more objects, and then click the Delete button.

Note	You cannot use this Delete button to remove individual rules from a library. To delete one or more rules from a library, you must download the entire library to your local file system, delete the rules, and then upload them back to the repository.

All deleted objects are immediately removed from the Repository.

Using the Diff Options

Identity Manager IDE allows you to compare (diff) directories or single objects on your local file system to their counterparts in the repository, and then view the differences side-by-side.

Setting Global Diff Options

Select IdM > Options to open the Repository Options dialog where you can specify the following global diffing options (which are all enabled by default):

Exclude lastModDate: Controls whether Identity Manager IDE excludes lastModDate modifications when you diff objects.
Exclude ids: Controls whether Identity Manager IDE excludes all auto-generated repository IDs when you diff objects.
Apply pattern substitution: Controls whether Identity Manager IDE applies the *-target.properties file (a Configuration Build Environment (CBE) pattern substitution file) when you diff objects.

Note	The Exclude lastModDate and Exclude ids options affect only those objects on the repository side. If you change any of the preceding options, Identity Manager IDE automatically updates the active window based on your selections. For example, if you click Options on the Identity Differences tab to open the Repository Options dialog and disable the Exclude ids option, the Identity Manager IDE automatically updates the information displayed on the Identity Differences tab, but does not update the Diff windows in the Editor.

Diffing Objects

After saving any modifications made to an object, you can diff the contents of a directory or of a single object, as described in the following sections:

Diffing a Directory
Diffing a Single Object

Diffing a Directory

To diff the contents of a directory,

Select IdM > Repository > Diff Objects from the menu bar.
Right-click the directory node (such as Custom Identity Manager Objects) and select Repository > Diff Objects.

Identity Manager IDE diffs all objects recursively down through the file system and then displays the results in the Identity Differences tab (Figure 1-30).

Figure 1-30  Identity Differences Tab

This tab consists of

A table that lists the Name, Status, and Location of all diffed files.

This table uses color-coded file names to indicate which files have been modified (blue) and which files are new and do not yet reside on the server (green).

Tip	Double-clicking a modified item in this table opens a Diff Output window so you can view the differences side-by-side.

The icons and buttons described in Table 1-6.

Table 1-6  Identity Differences Tab: Diff Icons and Buttons  

Click this Icon or Button:		To Perform this Task:
	Refresh	Retrieve any object changes from the local file system, re-diff those objects, and then redisplay the diff information on the Identity Differences tab. Important: You must click Refresh before using the Reload All, Upload All, or Diff All options to incorporate all of the newest changes for objects listed on the Identity Differences tab.
	Diff All	Diff all objects in a selected directory. When you diff the contents of a directory, the Identity Manager IDE also populates the Editor’s drop-down menu with the names of any objects that have been modified locally or in the repository. Select an object from this list to view its diff windows in the Editor.
	Reload All	Replace all of the modified objects listed on the Identity Differences tab with their counterparts from the repository.
	Upload All	Upload all of the modified objects listed on the Identity Differences tab to the repository.
		Filter buttons: Select any combination of these buttons to control how results display in the Identity Differences table.
		Unchanged: Filters all Unchanged results out of the list.
		Modified: Filters all Modified locally or in the repository results out of the list.
		Missing: Filters all Missing from Repository results out of the list.
	Options	Click to specify the global diffing options described in Setting Global Diff Options

Note	You must click Refresh before reloading, uploading, or diffing all to retrieve the newest changes for objects listed on the Identity Differences tab. If you do not Refresh, the Identity Manager IDE uses the older version of the object displayed on the Identity Differences tab. If you use any of icons or the Options button on the Identity Differences tab, the Identity Manager IDE automatically updates the information displayed in the Identity Differences tab — but does not update the Diff windows in the Editor.

Diffing a Single Object

To diff the contents of a single object,

Select IdM > Repository > Diff Object from the menu bar.
Right-click the object and select Repository > Diff Object.

The Identity Manager IDE Editor window updates to display a Local view and Remote view of the object, as shown in Figure 1-31.

Figure 1-31  Example Side-By-Side Display

The Editor window also provides the icons and button described in Table 1-7:

Table 1-7  Editor Diff Icons and Button  

Click this Icon or Button:		To Perform this Task:
	Refresh	Retrieve any object changes from the local file system, re-diff the object, and then redisplay the diff information in the Editor. Important: You must click Refresh before using the Replace local with repository or Upload local to repository options to include the newest changes made to that object.
	Replace local with repository	Replace a modified local object with its counterpart from the repository.
	Upload local to repository	Upload a modified local object to the repository.
	Options	Click to specify the global diffing options described in Setting Global Diff Options

Note	If the Diffing windows are open, and you click any of the icons or the Options button from the Editor, Identity Manager IDE automatically updates the information displayed in the Diffing windows — but does not update the Identity Differences tab.

---

Working with XML

This section describes how to work with XML in the Source Editor window. The information is organized into the following sections:

Editing XML
Using Auto-Completion
Identifying and Correcting Malformed XML
Validating XML

Editing XML

To edit an object’s XML,

Double-click the object node in the Project or Files window.
If the Source Editor view does not display by default, click the Source button.

When the object’s unfiltered XML displays in the Source Editor; you can edit, check, and validate the XML as needed.

Note	To edit an object that is not yet displayed in the Projects or Files window, select IdM > Repository > Open Objects. Specify all (or part) of the object name and the object type in the Open Objects dialog to locate that object on your local file system. If you try to open an object that has not been downloaded from the repository, Identity Manager IDE automatically downloads the object to your local file system, and then opens it in the Editor.

The Identity Manager IDE provides several options for editing an object’s XML:

Type the information directly into the Source editor window.
Right-click an object node in the Projects window and use the pop-up menus to access an Add dialog, where you can provide the necessary information.
Use the Palette window, which displays items from the workflow library and XPRESS categories. You can drag items from the Palette and drop them into a line in the Source Editor to create XML text at that point in the XML source.
Right-click in the XML file displayed in the Source Editor to insert Instance or Static Invoke statements. (See Inserting Invokes for more information.)

Using Auto-Completion

When you install the Identity Manager IDE, it registers the waveset.dtd definition file, which enables auto-completion for XML elements and attributes.

To use the auto-completion feature, begin typing an XML element or attribute, and then press Ctrl+Spacebar. NetBeans displays a list of the elements and attributes that can be used to automatically complete the element.

Identifying and Correcting Malformed XML

If you load a file into the Identity Manager IDE with malformed XML, or if you edit a file and the edits do not conform to the definition (DTD) file, a red error icon displays on the object’s top-level parent in both the Project and File windows.

Figure 1-32  Error Icon

If the Properties window is open, an error message is displayed in the window's description area. Or, you can use the invalid file's tooltip information to view the error message by placing your mouse over the file’s node.

When an object has malformed XML

The object’s child nodes do not display.
The Add, Clone, and Upload commands, some context menus and buttons become disabled.
You cannot use the Test Form or Test Rule features for Forms, Rule, or Library nodes.
XML added directly to the XML editor is not lost, but a node for the added object will not display until you fix the XML.

If you right-click in the Source Editor window and select Validate XML from the pop-up menu, the results — including a link to the malformed XML source — display in the Output window. Click this link and Identity Manager IDE highlights the line just below the malformed XML in the Source Editor window so you can easily locate and correct the problem.

Validating XML

You can immediately validate a object’s XML by right-clicking in the Source Editor and selecting Validate XML from the context menu.

Check the Output window for the results, which should be similar to the following message:

XML validation started.

Checking file:/H:/IdentityMgr/IDM_IDE_Project/Idm/objects/
System%20Configuration.xml...

XML validation finished.

---

Working with the Identity Manager IDE Debugger

The Identity Manager IDE provides a graphical Debugger that you can use to debug Identity Manager forms, rules, and workflows. You can use this Debugger to set breakpoints and watches, step through code, examine and modify variables, examine classes and the callstack, follow threads, and run multiple sessions.

This section describes how to use the Identity Manager IDE Debugger, and if you have previously used a code debugger for a procedural programming language, you should be familiar with the terms used here. The information is organized as follows:

Starting the Debugger
Setting Breakpoints
Using Watches
Stepping Through an Executing Process
Debugging Forms
Testing Rules
Debugging Workflows
Running the Debugger Outside a Test Environment
Using the Identity Manager IDE Tutorial: Debugging Forms, Rules, and Workflows
Stopping the Debugger

Caution	The Identity Manager IDE Debugger is enabled by default, but you should always disable it when you are finished debugging to prevent someone from accidently connecting it to an application server in your production environment. Instructions for disabling the Debugger, are provided in Disabling the Debugger.

Note	You should be aware of the following information when using the Identity Manager IDE Debugger: Do not use the Debugger in a production environment. Setting a breakpoint is a global setting; consequently, the Identity Manager IDE suspends incoming request threads when it reaches that breakpoint. The user specified in the project’s properties must have the Identity Manager Administrator capability. However, be aware that the Debugger can suspend threads that lock other users out of the system and display variables containing sensitive data from other users’ sessions. Given the powerful repercussions of misuse, exercise caution when assigning the right to run the Debugger. You must assign a private copy of the application server to users running the Debugger. If multiple users are developing on the same application server and one user connects a Debugger to the server, the other users will hit breakpoints and be locked out. The Debugger does not support clusters. For more information about working with workflows, forms, and views refer to the Sun Java™ System Identity Manager Workflows, Forms, and Views publication.

Starting the Debugger

To start the Identity Manager IDE Debugger, select Run > Debug Main Project from the main menu bar.

When you start a debugging session, the Identity Manager IDE automatically opens a set of Debugger windows that display runtime information about your program. From these windows, you can

Start and stop the debugging process
Navigate through the process execution
Set breakpoints (distinct stopping points in process execution)

Setting Breakpoints

You use breakpoint commands in the Debugger to halt the execution of an object before executing a specific line of code.

Note	Be aware that setting a breakpoint is a global setting. The Debugger suspends incoming request threads when it reaches a designated breakpoint — and this action happens regardless of which user is making the request.

When you are using the Debugger, breakpoints apply regardless of where you launched the form or workflow. While most debuggers allow you to set breakpoints only on source locations; the Identity Manager IDE Debugger also permits you to set breakpoints at conceptual execution points, such as Refresh view. In this case, the Debugger suspends operation whenever a Refresh view operation occurs. You can then step-into the Refresh view and watch the underlying form processing in progress.

You can view a summary of all source breakpoints in the Breakpoints window (typically located in the lower-left corner of the Identity Manager IDE). You can also click on a breakpoint in the Breakpoints window to navigate to that breakpoint in the Source Editor.

When it stops at a breakpoint, the Debugger also displays variables (that are in scope) at the current execution point.

Figure 1-33  Breakpoints Window

The easiest way to set a breakpoint is to click in the left margin of the Source Editor, immediately adjacent to the tag where you want to add a breakpoint.

You can also select Run > New Breakpoint from the main menu bar. When the New Breakpoint dialog displays, select XPRESS from the Debugger menu. The content in the dialog changes to provide the following options:

Breakpoint Type menu: Identity Manager is the only option that is available from this menu, and it is selected by default.
Global tab (default): Select to enable one or both of the following options:
All anonymous breakpoints — Sets a breakpoint on an anonymous source.
All named breakpoints — Use this option when you do not know which form a particular page is using. You can set this breakpoint and go to the page. You should then disable the All named breakpoints option and refine your breakpoints to something more specific within that particular form, or the Debugger will stop at every breakpoint.

Note	If you enable both options, the Debugger checks all breakpoints.

View Cycle tab: Select to set breakpoints associated with commonly used views (such as Checkin View, Checkout View, Get View, or Unlock View).

You can set code breakpoints based on the view processing that occurs during process execution. The most commonly invoked view operations are listed in this dialog, and available on each view.

Form Cycle tab: Select to set breakpoints associated with stages of form processing:

You can 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.

The tutorial examples provided with Identity Manager illustrate how to use breakpoints. See Using the Identity Manager IDE Tutorial: Debugging Forms, Rules, and Workflows.

Using Watches

The Identity Manager IDE Debugger enables you to use watches, which can be any valid XPRESS expression. Watches serve two purposes:

You can use simple <refs> to evaluate a specific set of variables.
You can use more-complex XPRESS expressions to help you determine what will happen if you make certain changes to the project.

The Debugger evaluates watches in the current context when you first enter the Debugger, and everytime it suspends while stepping or at a breakpoint. The Debugger also re-evaluates watches whenever you add or modify a watch.

The tutorial provided with Identity Manager (debugger-tutorial-workflow1.xml) illustrates how to use watches. See Example 1: Debugging a Workflow and a Rule.

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 workflows, 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 Identity Manager IDE (or in the Business Process Editor (BPE)):

Step-Into: Describes moving to the next point of execution on the current thread. Step-Into is always the smallest amount by which you can proceed through a process in the Source Editor.
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.

Step out: Describes moving incrementally until the execution stack is one less than the current. Similar to step-over. If the next point of execution has a different parent execution stack, it will stop there instead.

Tip	The following tips are provided 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). Use step-into when you want the smallest step possible through the code. Use 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 1-8 provides a snapshot of how the Identity Manager IDE Debugger would proceed through this code sample:

<A>    <B/> </A> <D/> (A, B, and D are some xml elements)

Table 1-8  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.)

Debugging Forms

This section explains how to work with anonymous sources and provides instructions for configuring and launching the form tester utility.

For detailed information about how the Identity Manager Forms engine processes a form, see Sun Java™ System Identity Manager Workflows, Forms, and Views.

Note	You can check the execution stack in the Call Stack window to see which pass is currently being processed.

Working with Anonymous Sources

When stepping through forms, the Debugger can identify anonymous sources.
Anonymous sources are forms (or portions of a form) that are generated on the fly (such as Login forms and MissingFields forms), and do not correspond to a persistent form that resides in the Identity Manager repository.

Because these forms do not reside in the repository, and thus lack unique identifiers, you cannot set individual breakpoints on anonymous sources. However, you can step through an anonymous source if you set an All anonymous sources breakpoint (as described in Setting Breakpoints).

This setting enables the Debugger to stop execution at points that do not have direct XPRESS source. As a result, the Debugger breaks any time it encounters a line from an anonymous source.

Configuring and Launching the Form Tester

Identity Manager IDE provides a form tester that lets you test forms in an external browser. The form tester is integrated with the Debugger, so you can also troubleshoot your forms.

To test a form:

Use one of the following methods to launch the form tester:
Select the form node in the Projects window and select IdM > Test Form from the NetBeans menu bar.
Right-click on the form in the Projects window and select Test Form from the pop-up menu.
Right-click within a <Form> element or any of its children in the Source Editor and select Test Form from the pop-up menu.

Note	A warning message displays to let you know that when Identity Manager IDE uploads your form to the repository it will replace (overwrite) the existing copy. You must indicate whether to continue or stop the test process.

When prompted, log into Identity Manager.

Tip	To avoid having to log in every time you test a form, use the following steps to modify the System Configuration object’s allowInterAppAuthenication property: Select IdM > Repository > Explore. From Explore Repository window, expand the Generic Objects node and double-click System Configuration to download the object. Double-click System Configuration.xml to view it in the Source Editor, and then scroll down (or use Edit > Find) to locate the allowInterAppAuthentication attribute. Change the attribute’s value to true and save your change.

Identity Manager IDE launches a new Identity Manager session in a browser window, and displays your form in the context of the Identity Manager Administrator user interface. In addition, information about the uploaded form displays in the Identity Manager IDE Repository Output window.

Note	Identity Manager provides a tutorial (debugger-tutorial-workflow1.xml) to help you understand how to debug forms. See Using the Identity Manager IDE Tutorial: Debugging Forms, Rules, and Workflows for instructions.

Testing Rules

Identity Manager IDE provides a rule tester that allows you to verify standalone rules and library rules as you edit them in the Source Editor. You provide values for any rule argument in the Source Editor and then “run” the rule. (You can also embed trace statements.)

You can use one of the following methods to launch the rule tester:

Select the rule node in the Projects window and select IdM > Test Rule from the NetBeans menu bar.
Right-click on the rule in the Projects window and select Test Rule from the pop-up menu.
Right-click within a <Rule> element or any of its children in the Source Editor and select Test Rule from the pop-up menu.

The following examples are provided to illustrate how the rule tester works.

Example 1: Testing Standalone Rules
Example 2: Testing Library Rules

Example 1: Testing Standalone Rules

This example illustrates how to test a simple, standalone rule:

Right-click Custom Identity Manager Object > Repository > Explore to view objects in the repository.
In the Explore Repository dialog, expand the Rules node and double-click Accountname First dot Last to open the rule.
Right-click in the Rule Tester Inputs window and select Add value from the menu.
When the New Value dialog displays, enter the following information, and then click OK:
Name: global.firstname
Type: String
Value: myfirst
Right-click in the Rule Tester Inputs window again, and enter another new value with the following information:
Name: global.lastname
Type: String
Value: mylast

Your Rule Tester Inputs window should look similar to Figure 1-34.

Figure 1-34  Rule Tester Inputs Window



You can now test the rule.

Select IdM > Test Rule from the NetBeans menu bar or right-click in the Source Editor window and select Test Rule from the pop-up menu.

Note	A message displays to warn you that the rule test will automatically save the rule and publish it to the repository. Click Yes or Always to proceed.

You should see output displayed in Rule Tester Output window that is similar to the following:

<String>myfirst.mylast</String>

<String>myfirst.mylast</String>

<String>myfirst.mylast</String>

Next, try testing the rule and running the Debugger at the same time.
If the Debugger is not already running, click the Debug Main Project button on the main menu bar.
Go the Source Editor window, click in the margin next to the <Rule> tag in the XML, and add a breakpoint.
Select Window > Debugging > Breakpoints to open the Breakpoints window.
In the Source Editor, right-click anywhere in the <Rule> element and select Test Rule from the pop-up menu.

The Debugger will stop at your breakpoint. (See the result in the Breakpoint window.)

Click the Step Into button seven times to step through your rule, observing the results in the Local Variables window.
Click Continue and observe the results in the Rule Tester Output window.

Example 2: Testing Library Rules

Testing library rules is very similar to testing standalone rules:

If necessary, download the Alpha Numeric Rules library from the repository and double-click the node to open this library rule in the Source Editor.
Expand the Alpha Numeric Rules nodes until you can double-click the stringToChars rule.

The testStr argument displays in the Rule Tester Inputs window because this rule declares a formal argument.

Give the testStr argument a value (right-click on the argument name in the Rule Tester Inputs window, select Add value, and enter a value in the New Value dialog).
Right-click in the Source Editor and select Test Rule to run the rule and observe the results in the Rule Tester Output window.

Note	Identity Manager provides a tutorial (debugger-tutorial-workflow1.xml) to help you understand how to debug rules. See Using the Identity Manager IDE Tutorial: Debugging Forms, Rules, and Workflows for instructions.

Debugging Workflows

Workflows are executed by a single Java thread, and are represented in the Call Stack window 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 1-9  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 always in bold/normal font. Actions that are not being executed are displayed in italics.
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.

To validate your workflow revisions after making changes, select the object or process in the Projects window, and then select Tools > Validate to test it. Check the Output window for messages.

Note	Identity Manager provides a tutorial (debugger-tutorial-workflow1.xml) to help you understand how to debug workflows. See Using the Identity Manager IDE Tutorial: Debugging Forms, Rules, and Workflows for instructions.

Using the Identity Manager IDE Tutorial: Debugging Forms, Rules, and Workflows

Identity Manager provides a tutorial (debugger-tutorial-workflow1.xml) to help you learn how to use the Debugger with forms, rules, and workflows. This tutorial contains sample forms, rules, and workflows that are used throughout this section.

Caution	Do not enable this tutorial in your production environment.

This section is organized as follows:

Getting Started
Example 1: Debugging a Workflow and a Rule
Example 2: Debugging a Workflow Containing a Manual Action and a Form
Example 3: Debugging the Tabbed User Form and Refresh View

Getting Started

To use the debugger-tutorial-workflow1.xml tutorial,

Use one of the following methods to import the debugger-tutorial-workflow1.xml file:
From Identity Manager, select Configure > Import Exchange File.
Type sample/debugger-tutorial.xml into the File to Upload field.
From the Console, enter:

import -v sample/debugger-tutorial.xml

If the file import successfully, you will see confirmation that the following files were loaded:

debugger-tutorial-workflow1
debugger-tutorial-workflow2
compute-full-name

Download debugger-tutorial-workflow1 and debugger-tutorial-workflow2 from the Repository to your project. (See Getting Objects from the Repository for instructions.)
After restarting the application server, select Run > Debug Main Project from the main menu bar to launch the Identity Manager IDE Debugger.

Example 1: Debugging a Workflow and a Rule

This example illustrates how to debug a simple workflow and rule that uses the workflow, including how to step-into and step-through workflow debugging and rule execution.

To complete this exercise you must perform the following steps:

Launch the process.
Start execution.
Step through the getFirstName thread.
Step into and over the getlastname thread.
Step into computefullname processing.
Step through rule processing.
Conclude workflow processing.

Step 1: Launch the Process

To launch the workflow debugging process:

In the Project window, expand the debugger-tutorial-workflow1.xml node.
Double-click the debugger-tutorial-workflow1.xml node to view the XML in the Source Editor. (If necessary, click the Source button.)

Figure 1-35  Open debugger-tutorial-workflow1.xml Source



Set a breakpoint at the start of the workflow by clicking once in the margin, to the left of the <WFProcess> tag.
If necessary, click the Debug Main Project button on the main menu bar to launch the Identity Manager IDE Debugger.
Log in to Identity Manager, and then select Server Tasks > Run Tasks.
When the Available Tasks page displays, click debugger-tutorial-workflow1.xml in the Name column.

Check the Identity Manager IDE Source Editor, and you should see that debugging halted at your breakpoint.

Also, note the following:

At the top of the Call Stack window, you should see Thread [thread name] (suspended), which 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, 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>).

In the Local Variables window, you should see a list of all variables that are currently in scope at the current point of execution, including

Table 1-10  Variables in Scope  

Variable	Description
Last Value	Result of the last evaluation
Interactive	Variable passed in by the view as an input to the process.
WF_CASE_OWNER	Implicit workflow variable
fullname	Variable declared in the workflow using <Variable> declarations
WF_CONTEXT	Implicit workflow variable
WF_CASE_RESULT	Implicit workflow variable
firstName	Variable declared in the workflow using <Variable> declarations
lastName	Variable declared in the workflow using <Variable> declarations

Now you are ready to start execution. Go to the next section for instructions.

Step 2: Start Execution

To start execution:

Click the Step-Into button on the Identity Manager IDE main menu bar.

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 1-36  Virtual Thread for the Start Activity



Double-click on the debugger-tutorial-workflow1 frame (two levels up) to highlight the WFProcess, which shows you the caller location.
Double-click on the bolded entry in the Call Stack window to return to the current line.
Click Step-Into again.

The Debugger moves to the </Activity> line in the Source Editor, and if you look in the Call Stack window, the Virtual Thread [start, step=0] is now pending outbound.

You can now proceed to Step 3, in the next section.

Step 3: Step Through the getFirstName Thread

To step-through the getFirstName thread:

Click Step-Into.

The Debugger highlights the transition to getFirstName.

Click Step-Into again.

Check the Call Stack window again, and notice that the Debugger created a new Virtual Thread for getFirstName as a result of this transition, and this Virtual Thread is currently in the ready state.

Figure 1-37  Virtual Thread for the Start Activity



Note that Virtual Thread [start, step=0] is still pending outbound because it is an and-split operation, and must take all possible transitions.

Click Step-Into again.

The Debugger jumps to the getFirstName activity in the Source Editor, and in the Call Stack window, the state changes from ready to executing.

Click Step-Into again.

The Debugger moves to the get action.

Now, click Step-Into three more times or until the Debugger reaches the </set> tag in the Source Editor.

Check the Local Variables window and note that the firstName value is set to <String>myfirstname</String> as a result of the </set>.

Figure 1-38  New firstName Value



Add a watch expression:
Open the Watches window (Window > Debugging> Watches).
Right-click in the window and select New Watch from the menu.
When the New Watch dialog displays, type the following XPRESS statement into the Watch Expression field, and then click OK.

<ref>firstName</ref>

The Debugger evaluates the watch expression, and its value should be <String>myfirstname</String>, which is the value you just set in Step 5.

Step 4: 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> line for getFirstName in the Source Editor.

Note that Virtual Thread (getFirstName, step=1) is now pending outbound in the Call Stack window.

Click Step-Into.

The Debugger returns to the Virtual Thread (start, step=0), and is about to process the transition to getLastName.

Click Step-Into.

Virtual Thread (start, step=0) becomes inactive because all transitions have been processed. As a result of this transition, getLastName is now in the ready state.

Click Step-Into.

At this point, Virtual Thread (start, step=0) goes away because it is inactive, and the Debugger moves to the Virtual Thread (getLastName, step=2), which is now in the executing state.

Click the Step-Over button to skip to the end of getLastName.

Check the Local Variables window, and the lastName variable should be set to <String>mylirstname</String>. Both the getFirstName and getLastName virtual threads are pending outbound.

Click Step-Into.

Check the Source Editor and note that the Debugger is on the Transition from getFirstName to computeFullName.

Click Step-Into.

In the Call Stack window, getFirstName becomes inactive and a new Virtual Thread, (computeFullName, step=3) is created.

Figure 1-39  New computeFullName Virtual Thread



Note that 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.

Step 5: Step Into computeFullName Processing

Use the following procedure to step-into computeFullName processing:

Click Step-Into.

The Virtual Thread (computeFullName, step=3) goes from pending inbound to ready because of this transition.

Click Step-Into.

Virtual Thread (computeFullName, step=3) is now executing.

Click Step-Into five more times.

If you check the Source Editor, you should see that the Debugger is now on the </argument> tag for firstName, and that Last Value in the Local Variables window is now <String>myfirstname</String>. This value is passed for the firstName argument.

Step 6: 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 Call Stack window, click the frame to move up one frame.

The <rule> call in debugger-tutorial-workflow1 is highlighted to indicate from where the rule is being called.

Double-click the bolded line to re-select that line.
Click Step-Into three more times or until the Debugger reaches the </ref> tag.

Now check the Local Variables window, and the Last Value entry is <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 Value entry is now <String>myfirstname mylastname</String>, which is the result of the <concat> expression.

Click Step-Into twice more and the Debugger returns to the </rule> tag.

Step 7: Conclude Workflow Processing

To conclude workflow processing:

Click Step-Into until you reach the </set> element.

The fullname variable is updated to <String>myfirstname mylastname</String>.

Click Step-Into twice more.

Virtual Thread (computeFullName, step=3) is now pending outbound.

Click Step-Into four more times.

Notice that end goes to ready, then executing, and then the Debugger reaches the </WFProcess> tag, which indicates that the process is now complete.

Click Step-Into.

In the Call Stack window, After Checkin View displays, indicating that the checkin-view operation that launched this workflow is now complete.

Click the Continue button on the Identity Manager IDE main menu bar to resume execution.

If the browser request has not timed out, the Task Results diagram with the process diagram displays.

Example 2: Debugging a Workflow Containing a Manual Action and a Form

This example illustrates how to debug a sample workflow containing a manual action and a form. Use debugger-tutorial-workflow2 tutorial file and perform the following steps:

Double-click debugger-tutorial-workflow2.xml to view the XML in the Source Editor.
Set a breakpoint on the <WFProcess...> tag.
If necessary, click the Debug Main Project button on the Identity Manager IDE main menu bar.
Log in to Identity Manager, and navigate to Server Tasks > Run Tasks.
When the Available Tasks page displays, select debugger-tutorial-workflow2 from the Name column.

Notice that the Debugger has stopped at the breakpoint you set.

Figure 1-40  New Breakpoint



Click Step-Into six times or until the Debugger marks <ManualAction... name='getNameAction'>.
Click Step-Into.
When the Stepping into Manual Action dialog displays to explain that form processing occurs in a different thread, click Yes or Always.
Set a breakpoint on the <Form> tag to see the processing occur.

When the form processing is complete, 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.

Note that the Debugger set breakpoints on the <Form> and </ManualAction> tags as indicated. In addition, the Call Stack window indicates After Checkin View, and you have stepped out of the workflow process because workflow processing 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.

Note the following entries in the Call Stack window:

Derivation — Indicates that form execution is on the derivation pass.
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.
Because this form contains no <Derivation> expressions, click Continue to proceed to the next processing phase. 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 just processed the title <Property> element, and the Last Value entry in the Local Variables window contains the value of this property.

Click Step-Into three more times.

The Debugger skips the form fields and goes directly to the </Form> element because this pass focuses only building the root component of the page.

Click Continue to begin the HTML Generation (subcomponents) pass of form processing.

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 Identity Manager browser window.

Return to the Identity Manager browser window, and enter your first and last name as prompted, and click Save.

Return to your Debugger frame, and note that the Debugger is now suspended on your breakpoint.

Expand the Variables subtree in the Local Variable window, and note that the names you just entered are displayed as the firstName and lastName values.

The Debugger is currently in the Confirmation phase of form processing.

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 and proceed to the Expansion phase of form processing.
Click Step-Into six times.

The Debugger moves to the <rule> tag of the <Expansion> of the variables.fullName field.

Click Step-Into five times, and the Debugger steps into the <Rule> element.
Click Step-Into seven times or until the Debugger reaches the </Rule> element.

The Last Value 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 you just ran. This value is a 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.

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 that you set previously when the Debugger stepped into the Manual Action. The firstName and lastName variables are the values that you entered. The fullName value is the result of the Expansion expression that just ran.

Click Step-Into five times until you get to <ManualAction... name='displayNameAction'>.
Click Step-Into again. (If prompted, click Yes or Always.)
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 Identity Manager 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.
Return to the Identity Manager window and you should see the workflow process diagram. Click OK.

Example 3: Debugging the Tabbed User Form and Refresh View

This sample debugging procedure illustrates how Debugger breakpoints apply regardless of where you launch a form or workflow.

To complete this procedure, you must perform the following steps:

Set a breakpoint.
Create a new user.
View before refresh view results.
View after refresh view results.
Step through the form.
Finish processing the form.

Setting a Breakpoint

To set a breakpoint:

Right-click in the Breakpoints window and select New Breakpoint from the menu.
When the New Breakpoints dialog displays, select XPRESS from the Debugger menu and then select the View tab.
Enable the Refresh View check box.

The Debugger will now execute a breakpoint whenever a view is refreshed during execution.

Creating New User

To create a new user:

In Identity Manager, select the Accounts tab, and then select New User from the top, left drop-down menu.
When the Create User page displays, enter a first name and a last name (for example, jean faux).
Click a different tab to trigger a refresh view operation.

Note that Identity Manager is now suspended because it hits a breakpoint.

Viewing Before Refresh View Results

Return to the Identity Manager IDE and note the following:

The Source Editor is now suspended on the Refresh View breakpoint that you set.
The Call Stack window lists Before Refresh View, which indicates the state of the view just before the refresh operation occurred.
The Local Variables window displays the view just before it was refreshed.

In the Local Variables window, 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 Call Stack window lists After Refresh View, indicating it now displays the state of the view just after the refresh occurred. Note that the fullname value is now jean faux.

Click Continue again.

The form resumes execution. Return to the Identity Manager browser window and change First Name to jean2. Click a different tab to trigger another refresh.

Back in the Identity Manager IDE Source Editor, the 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 Call Stack window lists Before Expansion, which indicates that the form variables have not been expanded.

Click Step-Into again.

The Call Stack window now lists Before Expansion, iteration=0, indicating that you will see the form variables before the first Expansion pass.

Click Step-Into again.

The Call Stack window lists an anonymous source (Tabbed User Form (Anonymous, line: 3)(begin)). The anonymous source is a wrapper form created on the fly and it is related to the MissingFields 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, notice that the Last Value entry at the </concat> tag is
jean2 faux, and that the form_outputs value is global.fullname: jean2 faux.

Complete Form Processing

To complete form processing:

Click Step-Out seven times.

At this point, the Call Stack window should indicate:

Refresh View (User)
After Expansion

The Local Variables window displays the state of the form variables after all expansions have run.

Click Step-Out again.

You have now reached After refresh view. The Local Variables window now displays the view variables.

Expand the global subtree.

Note that fullname is now jean2 faux.

Click Continue.

Debugging Java and XPRESS

The following example illustrates how to create and compile custom Java code and how to use both the XPRESS debugger and Java debugger at the same time.

Note	The Identity Manager Project (Remote) does not support Java debugging.

Tip	Before starting this example, turn off the NetBeans HTTP monitor to remove the extra window: Expand the Servers node in the Runtime window, right-click Bundled Tomcat, and select Properties from the pop-up menu. When the Server Manager dialog displays, disable the Enable HTTP Monitor box, and then click Close.

Perform the following steps to create custom Java code:
In the Projects tab, right-click Source Packages and select New > Java Class from the pop-up menu.
Enter TestClass in the Class Name field and testpackage in the Package field.
When the testpackage node displays, add the following method:

public static String concat(String s1, String s2) {    return s1+s2; }

Save the class.
Perform the following steps to create a rule that calls the Java code:
In the Project window, right-click Custom Identity Manager Objects and select New > File/Folder from the pop-up menu.
When the New File dialog displays, select Sun Identity Manager Objects from the Categories list, and then select Rule from the File Types list.

Figure 1-41  Choosing the Rule File Type



When you are done, click Next.
When the New Rule screen displays, enter Test Rule into the File Name field, and then click Finish.

Figure 1-42  Choosing the Rule File Type



The Projects window updates to display Test Rule.xml.

Select Test Rule. xml and then click the Source tab in the Editor window to view the XML.
If necessary, change <Rule name='New Rule' to <Rule name='Test Rule'.
Insert the following call to your method and then save the rule:

<invoke class='testpackage.TestClass' name='concat'>         <ref>arg1</ref>         <ref>arg2</ref> </invoke>

Perform the following steps to build the custom Java code and start the application server:
Right-click on the project node and select Debug Project.

Wait while Identity Manager IDE builds the Web application and starts the server (which takes a few minutes).

When prompted, enter your password.

If you check the log file, you will see that you rule was automatically uploaded.

When a browser window displays, you can close it.

If you want to disable the browser, right-click the project and select Properties. In the Project Properties window, Run and uncheck Display Browser on Run.

Set a breakpoint in the Java code and one in the XPRESS code:
In Test Rule.xml, set a breakpoint by clicking in the margin to the left of the <Rule tag.
In TestClass.java, set a breakpoint by clicking in the margin to the left of the return s1+s2; statement.
Use the rule tester to call both breakpoints:
Select Window > Rule Tester Inputs from the NetBeans menu bar to open the Rule Tester Inputs window.
Select Test Rule.xml in the Projects window.
Right-click in the Rule Tester Inputs window and select Add value. When the New Value dialog displays, enter the following information, and then click OK:
Name: arg1
Type: String
Value: myvalue1
Right-click in the Rule Tester Inputs window again and select Add value. When the New Value dialog displays, enter the following information, and then click OK:
Name: arg2
Type: String
Value: myvalue2
Expand the Test Rule.xml node, right-click Test Rule, and then select Test Rule from the pop-up menu.
When a message displays asking you to confirm whether to save the rule, click Always.

At this point, you have reached the breakpoint on your rule.

Click the Step-Into button six times to reach the breakpoint in your Java code.

Note that you are now in the Java Debugger, and that your Java variables are now displayed in the Local Variables window.

Note	When you are debugging Java and XPRESS at the same time, there are actually two debuggers running at the same time and they are not aware of each other. Both debuggers have their own breakpoints and their own stepping-into states. Step-into will not step from XPRESS code into Java code unless there is a breakpoint in the Java code.

Click Continue.

Note that you have returned to the </invoke> tag in the XPRESS Debugger. You should also see that Last Value shows myvalue1myvalue2 as the invoke result.

Note	When leaving the Java code, always click Continue to resume executing the Java debugger. Debugging performance becomes very sluggish if you leave the Java debugger in a stepping state.

Click Continue again to see the rule results in the Rule Tester Output window.
Modify the rule as follows, and then rerun the rule:
Change <ref>arg1</ref> to <s>myprefix</s>.
Right-click the rule and select Test Rule.
Click Continue twice and view the new results in the Rule Tester Output window.
Modify the Java code as follows, and then re-run:
Change return s1+s2; to return s1+s2+"mysuffix";
Because you changed the Java code, you must rebuild and redeploy.
Right- click the project and select Debug Project.
Right-click the Test Rule node and select Test Rule.
Click continue twice and you should now see the following results in the Rule Tester Output window:

<String>myprefixmyvalue2mysuffix</String>

Stopping the Debugger

To stop the Identity Manager IDE Debugger, select Run > Finish Debugging Session from the main menu bar.

Disabling the Debugger

You should always disable the Debugger when you are finished debugging to prevent someone from accidently connecting it to an application server in your production environment.

To disable the Debugger, use the following steps:

From Projects tab, expand the Generic Objects node and double-click System Configuration to view the XML in the Source Editor window.
Scroll down (or use Edit > Find) to locate the serverSettings.default.debugger.enabled attribute and change the value to false, as shown in the following example:

<Attribute name='serverSettings'> <Object> <Attribute name='default'> <Object> <Attribute name='debugger'> <Object> <Attribute name='enabled'> <Boolean>false</Boolean> </Attribute>

Select File > Save from the main menu bar to save your change.
Restart your application server.

Running the Debugger Outside a Test Environment

When you encounter problems in production that require debugging, it is best to try to reproduce and debug those problems in a test environment. Setting breakpoints in the Debugger can quickly bring down the application server in your production environment, where a large volume of traffic occurs. You might also block others from using the system (depending where you set the breakpoints).

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 Identity Manager IDE to edit the System Configuration object by setting the SystemConfiguration serverSettings.server-a.debugger.enabled property to true.
Restart server-a so that the change to the System Configuration property setting can take effect.
Change your project settings; specifying the proper host (server-a), port, context path, user, and password.
Start the Debugger.
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.

---

Uninstalling Identity Manager IDE from NetBeans

If for any reason, you want to uninstall the Identity Manager IDE module from NetBeans, perform the following steps:

If necessary, open NetBeans.
Select Tools > Module Manager from the NetBeans menu bar.

The Module Manager dialog displays (Figure 1-43), listing all of your installed modules. The Active column indicates which of these modules are enabled.

Note	The Identity Manager IDE allows you to disable the modules you do not need to minimize start-up time and save memory. Disabled modules are not deleted from your installation directory, but are simply ignored by the Identity Manager IDE. You can re-enable disabled modules at any time.

Figure 1-43  Selecting the Module to Uninstall



Select Sun Identity Manager from the list of modules.
Click Uninstall.
A pop-up displays, asking you to confirm that you want to uninstall the Sun Identity Manager module. Click OK to proceed with the uninstall process.
When the process is complete, close the Module Manager.

---

Troubleshooting Identity Manager IDE

This section provides information you might need to troubleshoot issues with Identity Manager IDE.

Unable to Delete Errors

Unable to Delete error messages can occur in the following circumstances:

If you select IdM > Manage Embedded Repository while the server is running, the following error message will display:

Unexpected Exception: 'Unable to delete [NetbeansHome]\[Project]\idm-repository\idm.data'. See the logs for details.'

To correct this error, shut down the server and try again.

If you try to performing a “clean” while the server is running, a number of error messages in the following form will result:

Unable to delete file ../image/idm/WEB-INF/lib/*.jar

To correct this error, shut down the server and try again.

Out of Memory Errors

If you experience out-of-memory errors as you work with Identity Manager IDE, you might have to increase the NetBeans memory settings. Consult your NetBeans product documentation for instructions.

Tomcat Manager Dialog Displays, Requesting User Name and Password

If you are working with the standard Identity Manager IDE project, start the bundled Tomcat instance, and the Tomcat Manager dialog displays, it generally indicates one of the following conditions:

Multiple Tomcat instances are running.

You must insure that only one Tomcat instance is running on the host machine and configured to listen on the same port as the bundled Tomcat.

A credentials mismatch has occurred.

The credentials stored as part of the bundled Tomcat server must match those stored on the Server Manager’s Username and Password fields. For more information about these field values, go to the following website:

http://wiki.netbeans.org/wiki/view/FaqInstallationDefaultTomcatPassword

To check the port number of the bundled Tomcat and the stored credentials:

Select the Identity Manager IDE Runtime tab and expand the Servers and Bundled Tomcat nodes.
Right-click the Bundled Tomcat node and select Properties from the pop-up menu.
When the Server Manager dialog displays, check the Server Port, Username, and Password field values.

Previous      Contents      Index      Next

---

.   Copyright 2007 Sun Microsystems, Inc. All rights reserved.