test

Sun Identity Manager 8.1 Release Notes

Chapter 7 Documentation Additions and Corrections

This section contains new and corrected information that was required after the Identity Manager 8.1 documentation set was published.

This information is organized as follows:

Identity Manager 8.1 Business Administrator's Guide

This section contains new information and documentation corrections for the Sun Identity Manager 8.1 Business Administrator’s Guide:

The following information will be added to the Security chapter:

Identity Manager 8.1 System Administrator's Guide

This section provides new information and documentation corrections for the Sun Identity Manager 8.1 System Administrator’s Guide.

This information includes the following:

Old Package Name 

New Package Name 

com.waveset.adapter.ADSyncFailoverTask 

com.waveset.task.ADSyncFailoverTask 

com.waveset.adapter.ADSyncRecoveryCollectorTask 

com.waveset.task.ADSyncRecoveryCollectorTask 

com.waveset.adapter.SARunner 

com.waveset.task.SARunner 

com.waveset.adapter.SourceAdapterTask 

com.waveset.task.SourceAdapterTask 

Identity Manager 8.1 Deployment Guide

This section contains new information and documentation corrections for the Sun Identity Manager Deployment Guide.

System Configuration Object Documentation Changes

The description of the System Configuration object should contain the following information about these attributes:

ProvisioningDisabledUserShouldThrow – When set to true, any attempt to provision a disabled user to a resource will be prevented and will produce an error. When the attribute is not set to true, then the provisioning will still be prevented, but it will not produce an error. (ID-20064)

security.delegation.historyLength – Controls the number of previous delegations that are recorded. (ID-13331)

runPasswordLoginOnSuccess – When set to true, Identity Manager will run the Password Login workflow when a user logs in successfully by answering the authentication questions. By default, the value of this property is false. (ID-10030)

PasswordSyncThreshold - If password sync is enabled for a resource for which Identity Manager can also initiate password changes, you can use this setting to help prevent a loop-back password change. (ID-7887) When you initiate a password change from Identity Manager, it will set the password on the resource, and the PasswordSync library will notify Identity Manager of the change. Identity Manager will then compare the lastPasswordDate on the user object to the current time. If this difference is less than the PasswordSyncThreshold, Identity Manager will ignore the password change. In this way, the extra or unnecessary password change will be appropriately ignored.

PasswordSyncResourceExcludeList – Lists resource names that should always be excluded from synchronization.(ID-3275)

process.handleNativeChangeToAccountAttributes – When set to true, enables attribute value auditing. By default, this property is off. (Note: This enables attribute value auditing both for the reconciliation process and for the provisioner.) (ID-3275)

sources.subject – Specifies the login name of administrator designated as the owner of the source adapter task. (ID-19694

sources.host – Specifies the server on which the source adapter task runs.

security.saveNoValidateAllowedFormsAndWorkflows – Lists the IDs of forms and workflows that will be processed as a SaveNoValidate action. All other forms and workflows will be processed as a Save. If this list is not present, the behavior remains the same for all forms and workflows (all forms and workflows will be processed as SaveNoValidate.) (ID-19474)

Data Exporter Changes

Data Exporter provides the means to periodically export data that is managed or has been processed by Identity Manager to a set of DBMS tables for further processing. The export process is intentionally open to customizations, some of which may require manual intervention for the proper behavior. The Identity Manager configuration objects that are relevant to Data Exporter are preserved and updated appropriately. However, some exporter customization is done to files within the web application, and these take special handling.

During the upgrade process, Identity Manager overwrites all unmodified Data Exporter files in the $WSHOME and $WSHOME/exporter directories. If you made changes to any Data Exporter files, then the upgrade process leaves your modified version in place and installs the newer version of the file in $WSHOME/patches/Identity_Manager_8_1_0_0_Date/filesNotInstalled. If you want to merge the new functionality with your customizations, you must do this manually.

Note that the following files in $WSHOME are often customized:

model-export.dtd
model-export.xml
model-export.xsl
exporter/exporter.jar
exporter/create_warehouse.*
exporter/drop_warehouse.*
exporter/hbm/*.hbm.xml

The upgrade steps you must perform vary depending on whether you customized Data Exporter in 8.0 and your plans for Data Exporter in 8.1

After 8.1 is installed, if the 8.1 version of model-export.xml is in place, you can see the new data types and attributes by looking at the schema file at http://server:port/idm/model-export.xml. New types and attributes are flagged with the 8.1 release number.

Identity Manager 8.1 Deployment Reference

This section contains new information and documentation corrections for Sun Identity Manager Deployment Reference.

Forms-Related Documentation Issues

The following description of adding a password confirmation challenge to forms is missing from this chapter: (ID-7604)

You can use the RequiresChallenge form property to add a password confirmation challenge to select forms. When this feature is enabled, Identity Manager will challenge the currently logged-in administrator for his password before processing a request. The forms that supporting this option include:

userForm (Tabbed User Form, Wizard User Form, Default User form)

changePassword (by default, Change User Password form)

resetPassword (by default, Reset User Password form)

The property is specified different for each of the forms.

Setting the RequiresChallenge Property for User Forms

To add a password confirmation challenge to a user form, add the following RequiredElement element as shown below, with substitutions for password, email, and fullname:


<Property name='RequiredChallenge'>
    <List>
      <String>password</String>
      <String>email</String>
      <String>fullname</String>
    </List>
</Property>

The value of the property is a list of one or more of the following User view attribute names: applications, adminRoles, assignedLhPolicy, capabilities, controlledOrganizations, email, firstname, fullname, lastname, organization, password, resources, roles.

Setting the RequiresChallenge Property for Change Password and Reset Password Forms

To add a password confirmation challenge to either a changePassword or resetPassword form, add the following <RequiresChallenge> element as shown below, with substitutions for password, email, and fullname:

<Property name='RequiresChallenge' value='true'/>

where the value of the property can be either "true" or "false".

If the property is set to "true" in the form, Identity Manager will challenge the current administrator who is requesting the change to enter the password he used to log in to Lighthouse. If the challenge is not successful (that is, the current administrator's password is not entered), Identity Manager will not permit the change. If the challenge is successful, Identity Manager will permit the change request to proceed. Both password management forms support the use of the 'RequiresChallenge' form property. When this property is set to true, the user is prompted to enter the old password after specifying the new password.

Overriding Version Information

You can create two custom message catalog keys that prevent Identity Manager from displaying the version information when a user places the cursor over the help button. The UI_END_USER_VERSION key hides the version information on the end user interface, while the UI_VERSION key is used by the administrator interface.

Setting the value of the key to the empty string prevents any version information from being displayed.

The following example disables version information for both interfaces.

<Waveset>
   <Configuration name="sampleCustomCatalog">
      <Extension>
         <CustomCatalog id="defaultCustomCatalog" enabled="true">
            <MessageSet language="en" country="US">
               <Msg id="UI_END_USER_VERSION"></Msg>
               <Msg id="UI_VERSION"></Msg>
            </MessageSet>
         </CustomCatalog>
      </Extension>
   </Configuration>
</Waveset>

Other Forms-Related Issues

The "Forms" chapter is missing the following discussion: (ID-18869)

By default there are two implementations of the change password form:

The End User Password Change form is the default password change form. It presents a simple set of fields with which the user can change their password. The password policies for all resources that are assigned to the user are aggregated and summarized, and Identity Manager applies the password change to all assigned resources.

The Basic Change Password Form is present in both the Administrator and User Interfaces. It provides information about the resources that are assigned to the user and allows the user to individually select on which resources Identity Manager will change the password.

Both password management forms support the use of the 'RequiresChallenge' form property. When this property is set to true, the user is prompted to enter the old password after specifying the new password.

Issues Common to Both Workflows and Forms

The Forms and Workflow chapters of this guide are missing the following discussion about assigning scope to <Variable> elements: (ID-14915)

Identity Manager assigns a scope to all <Variable> elements when the element is declared. If you do not assign a value to the scope attribute, Identity Manager assigns it a value of local, which means that the variable can be accessed only within the XPRESS section that is declared in.

Additional Variable attributes that define scope include:

input -- Declares that the <Variable> element has local scope and that the value can be initialized by the caller.

output -- Declares that the <Variable> element has local scope but can be returned to the caller.

external -- Declares a <Variable> that has non-local scope - that is, assignments to this variable will result in assignment to this variable in the scope it was first declared in.

The following discussion of the Identity Manager whitelist feature is missing from this chapter. (ID-19474)

The Identity Manager whitelist feature makes it possible to check forms and workflows that use the SaveNoValidate action against a list of IDs or form names. Identity Manager checks the whitelist for either form names or form-owner IDs.) The list of IDs, called saveNoValidateAllowedFormsAndWorkflows, is located in the security attribute in the System Configuration object. If the form name or owner ID is on the whitelist, the form or workflow can use the SaveNoValidate action. If the form name or the owner ID is not on the list, the form or workflow is processed using a Save action. If the list is not present, all forms and workflows can be processed as SaveNoValidate.

To implement this feature in your deployment, you must add any forms or workflows using SaveNoValidate to the saveNoValidateAllowedFormsAndWorkflows list in the System Configuration object. To see the IDs or form names that you must add, check the syslog or turn trace level 4 on for com.waveset.ui.util.GenericEditForm and submit any custom forms or workflows that use SaveNoValidate. A warning including the ID will be logged. If you are getting "null" form names in the syslog, confirm that the form in the TaskDefinition that was run has a name attribute.

Workflow-Related Issues

The Workflow chapter is missing the following discussion of the handleNativeChangeToAccountAttributes workflow (ID-3275):

Whenever Identity Manager detects a native change (that is, a change not performed through Identity Manager) to the values of an auditable attribute of a resource account, it responds by running the handleNativeChangeToAccountAttributes workflow, which is associated with this System Configuration object attribute:

<Attribute name='process'>
  <Object>
    <Attribute name='handleNativeChangeToAccountAttributes' value='Audit Native
      Change To Account Attributes'/>
  </Object>
</Attribute>

This workflow logs the native change events to the event log if you have enabled the Changes Outside Lighthouse audit filter. Otherwise, Identity Manager ignores the event. Warning: Be careful which methods you call from any workflow that replaces the default workflow listed above.

Because Identity Manager launches this workflow whenever a resource account fetch reveals a native change, it must not invoke any method or workflow that would trigger another fetch of the same resource account. For example, an infinite loop will result if you call any WorkflowServices method that assembles the user view: getView(User),checkoutView(User) and possibly checkinView(User).

The fact that Identity Manager handles each native change by running a workflow allows you to hook the native change event, and to handle that native change however you see fit by replacing or adding to the default native change workflow. For example, you might choose to send email to an administrator or a user, to record the event in a database, to queue an update that would back out the native change, or even to pull that native change into and push it back out to the other resources.

The Workflow chapter of this guide is missing the following description of how to specify the subject or administrator of a source adapter task. (ID-19694).

You can assign a subject or administrator to a Source adapter task and designate the server on which it runs by editing the following attributes of the system configuration object. source.subject specifies the login name of administrator designated as the owner of this task. sources.host specifies the server on which the task runs. The new values in the configuration object are by default:

<Attribute name='sources'>
           <Object>
             <Attribute name='hosts'/> <!-- any host is the default -->
           <Attribute name='subject' value='Configurator'/>
         </Object>
         </Attribute>

Identity Manager 8.1 Resource Reference

This section contains new information and documentation corrections for Sun Identity Manager 8.1 Resources Reference.

The discussion of identity connectors is missing the following information about how ConnectorAdapter implements the run() method: The arguments passed to the runResourceAction service are passed to the script (defined in the ResourceAction) as direct script variables. (ID-19856)

Identity Manager 8.1 Service Provider Deployment Guide

This section contains new information and documentation corrections for Sun Identity Manager Service Provider 8.1 Deployment.

Developing Customer Adapters

The ResourceAttribute element may contain a ValidationPolicy element. A validation policy ensures the value a user specifies on the Resource Parameters page meets the requirements defined in a separate policy object.

The following sample causes the adapter to use the Port Policy to ensure the specified value is valid. The default Port Policy checks the value is an integer between 1 and 65536.

<ResourceAttribute name=.Port. value=.123.>
   <ValidationPolicy>
      <ObjectRef type=.Policy. id=.#ID#PortPolicy. name=.Port Policy./>
   </ValidationPolicy>
</ResourceAttribute>

Identity Manager IDE Frequently Asked Questions (FAQ)

This FAQ answers some commonly asked questions related to using the Identity Manager IDE.

The information is organized into these categories:

Using NetBeans

Question:

Which version of Netbeans should I use?

Answer:

Use the Netbeans version referenced in the Identity Manager product documentation provided for the Netbeans plugin version you are using.

Note –

Always use the exact version referenced because even patch releases can cause major functionality to break.

Question:

The Netbeans plugin was working, I did something, and now it is no longer working. What could be causing this problem?

Answer:

This problem is commonly caused by a corrupt file in your .netbeans directory. Generally, deleting your .netbeans directory and re-installing the NetBeans plugin resolves the problem. (Deleting the .netbeans directory effectively uninstalls the NetBeans plugin. You lose all of your user settings, but the contents of your project will be safe.)

    The steps are as follows:

  1. Shutdown NetBeans.

  2. Delete the .netbeans directory.

  3. Start NetBeans.

  4. Install the NetBeans plugin.

  5. Restart NetBeans.

Working with Projects

Question:

Building and running a project is taking a very long time, and the Identity Manager IDE seems to be copying a lot of files. What could be causing this problem?

Answer:

This problem can occur for the following reasons:

Question:

Now that I have created an Identity Manager project, what files should be checked into source control?

Answer:

See the “CVS Best Practices” section in the Identity Manager IDE README.txt for information.

Question:

What are the best practices for using project management in CVS?

Answer:

See the “CVS Best Practices” section in the Identity Manager IDE README.txt for information.

Question:

When are objects imported into the repository?

Answer:

See Working with the Repository for information.

Question:

How do I add a new JAR to the project?

Answer:

See the “How to add a new JAR dependency” section in the Identity Manager IDE README.txt.

Working with the Repository

Question:

Which repository should I use for my sandbox repository?

Answer:

Use the embedded repository for your sandbox— particularly if you are using Identity Manager 7.1 (or higher), which has an HsSQL repository available. You lose functionality if you do not use the embedded repository.

Refer to the “Working with the Repository” section in the Identity Manager IDE README.txt for more information.

Question:

When are objects imported automatically?

Answer:

You have to configure Identity Manager IDE to import objects automatically.

The steps are as follows:

  1. Select Repository > Manage Embedded Repository from the IdM menu.

  2. Enable the Automatically Publish Identity Manager Objects option on the Manage Embedded Repository dialog.

    Note –

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

  3. Select Project > Run Project or Project > Debug Project.

    The Identity Manager IDE automatically imports all objects that have changed since the last time you ran the project.

    Tip –

    Automatically publishing Identity Manager objects increases the time needed to start the server. To minimize server start time, disable this option and explicitly upload objects to the repository.

Question:

What is the most effective way to upload objects?

Answer:

Use one of the following methods to upload modified objects:

Either method uploads the object(s) directly to the server, so there is no cache latency issue and it is much faster than using Run Project or Debug Project. The Upload Objects feature is available regardless of which repository you are using.

Using the Identity Manager IDE Debugger

Note –

The Netbeans embedded application server automatically shuts down whenever you perform any of the following project operations:

Question:

The Identity Manager IDE Debugger is sluggish. What could be causing this problem?

Answer:

To improve the Debugger’s performance:

Question:

I cannot set a breakpoint in the Debugger. What could be causing this problem?

Answer:

The following conditions might prevent you from setting a breakpoint:

Question:

I set a breakpoint in the Debugger and it is not suspending on the breakpoint. What could be causing this problem?

Answer:

There are two things to check:

Working with Rules

Question:

When developing rules in Netbeans, why is design mode not available for a Rule Library?

Answer:

The design mode functionality is available from the explorer tree in Projects view. Use the following steps:

  1. Expand the library node and right-click a rule.

  2. When the pop-up menu displays, select Properties and then click Body.

Localization Scope

Historically, Identity Manager does not localize resource objects and functions, primarily because they are mostly samples that get loaded (through init.xml) during initialization of Identity Manager, and because the attributes of object types can vary between actual customer deployments, depending on the level of customizations. Following is a list of areas where users might encounter English: (ID-16349)

Working with the Identity Manager Profiler

Identity Manager provides a Profiler utility to help you troubleshoot performance problems with forms, Java, rules, workflows, and XPRESS in your deployment.

Forms, Java, rules, workflows, and XPRESS can all cause performance and scale problems. The Profiler profiles how much time is spent in these different areas, enabling you to determine if these forms, Java, rules, workflows, or XPRESS objects are contributing to performance and scale problems and, if so, which parts of these objects are causing the problems.

This section explains how to use Identity Manager’s Profiler and provides a tutorial to help you learn how to troubleshoot performance issues in your deployment.

The information is organized into the following topics:

Note –

Identity Manager Profiler is only supported on version 7.1 Update 1 and later.

Overview

The section provides an overview of the Identity Manager’s Profiler’s features and functionality. The information is organized as follows:

Major Features

You can use the Profiler utility to

How the Profiler Locates and Manages Source

This section describes how the Profiler looks up and manages the source for the following Identity Manager objects:

Tip –

In Call Tree view or Hotspots view, you can double-click any node that corresponds to a Java method, workflow, form, rule, or XPRESS to view the source for that node.

For Forms, Rules, Workflows, and XPRESS Objects

When you take a snapshot with the Profiler, the server evaluates all of the profiling data and discovers on which sources the data depends. The server then fetches all of these sources from the repository and includes them in the snapshot. Consequently, you can be sure that the Identity Manager objects displayed in the snapshot are accurately reflecting the point at which the snapshot was captured.

This process adds to the size of the snapshot, but the source size is actually a relatively small fraction of the total size. As a result, you can send a snapshot to Sun’s Customer Support without having to send your source files separately.

For Java Source

When you take a snapshot of Java source, the client downloads the snapshot and then goes through the snapshot to capture all referenced Java sources from the project. When you save the snapshot, the client zips the sources and attaches them to the end of the snapshot.

Then, when you view the snapshot and go to the Java source, the client first checks the content of the snapshot. If the client cannot find the content there, it checks the project’s content. This process allows you to send a snapshot containing profiling data from both your custom Java code and Identity Manager code.

Note –

In a Java source snapshot, do not assume the source is up-to-date with the server or always available.

Statistics Caveats

The following sections contain information to consider when you evaluate results provided by the Profiler:

Self Time Statistics

To compute a root node’s Self Time statistic, the Profiler subtracts the times of all children nodes from the root node’s total time.

Consequently, an uninstrumented child node’s time is reflected in the root node’s self time. If a root node has a significant self time, you should certainly investigate why. You might not have the proper methods instrumented and so you are looking in the wrong place.

For example, assume method A calls method B.

Method A takes a total time of 10 seconds (where total time includes the call to B) and the call to B takes a total time of 10 seconds.

If both A and B are instrumented, the call stack reflects that information. You will see that A has a self-time of 0 seconds and that B has a self-time of 10 seconds (where 10 seconds was actually spent in B). If, however, B is not instrumented, you only see that the call to A takes 10 seconds and that A’s self-time is 10 seconds. Consequently, you might assume the problem lies directly in A rather than in B.

In particular, you might notice large self times on JSPs during their initial compile. If you reset the collected results and then re-display the page, the self time value will be much less.

Constructor Calls

Because there are limitations in the Java instrumentation strategy, initial calls to this() or super() will appear as a sibling to the constructor call, rather than as a child. See the following example:


class A
{
   public A()
   {
      this(0);
   }
   public A(int i)
   {
   }
}

and:

class B
{
   public static void test()
   {
      new A();
   }
}
The call tree will look like this:
B.test()
   -A.<init>(int)
   -A.<init>()
Rather than this:
B.test()
   -A.<init>()
      -A.<init>(int)

Daemon Threads

Do not be mislead by the seemingly large amount of time spent in a number of Identity Manager’s daemon threads, such as ReconTask.WorkerThread.run() or TaskThread.WorkerThread.run(). Most of this time is spent sleeping, while waiting for events. You must explore these traces to see how much time is actually spent when they are processing an event.

Getting Started

This section describes how to start the Profiler and how to work with various features of the Profiler’s graphical user interface. This information is organized as follows:

Before You Begin

Because the Profiler is very memory intensive, you should significantly increase the memory for both your server and the Netbeans Java Virtual Machine (JVM).

    To increase your server’s memory,

  1. Open the Netbeans window and select the Runtime tab.

  2. Expand the Servers node, right-click Bundled Tomcat, and select Properties from the menu.

  3. When the Server Manager dialog displays, clear the Enable HTTP Monitor box on the Connection tab.

  4. Select the Platform tab, set VM Options to -Xmx1024M, and then click Close.

    To increase the Netbeans JVM memory,

  1. Open the netbeans-installation-dir \etc\netbeans.conff file and locate the following line:

    netbeans_default_options="-J-Xms32m -J-Xmx ...

  2. Change the -J-Xmx value to -J-Xmx 1024M.

  3. Save, and then close the file.

When you are finished, you can start the Profiler as described in the next section.

Starting the Profiler

You can use any of the following methods to start the Profiler from the Identity Manager IDE window:

Note –

The Start Identity Manager Profiler on Main Project icon is enabled when the main Identity Manager project is version 7.1 Update 1 or later.

When you start the Profiler, the Profiler Options dialog displays so you can specify which profiling options you want to use. Instructions for setting these options are provided in Specifying the Profiler Options.

Using the Profiler

This section describes the features of the Profiler graphical user interface, and how to use these features. The information is organized as follows:

Specifying the Profiler Options

The Profiler Options dialog consists of the following tabs:

Use the options on these tabs to indicate which objects to profile and which elements to display in the profile.

After specifying the Profiler options, click OK to start the Profiler. Depending on your project configuration, the Profiler does one of two things:

Note –

You can select IdM -> Set Identity Manager Instance to control the Identity Manager Instance action for the project.

Mode

The Mode tab provides the following options:

IDM Object Filters

The IDM Object Filters tab provides the following options:

Java Filters

Select the Java Filters tab to

Java filters are given in terms of method patterns, and they are expressed in patterns that include or exclude based on canonical method name. Where a canonical method name is:

fully-qualified-class-name.method-name(parameter-type-1, parameter-type-2, ...)

Note –

For constructors, method-name is <init>.

Here are a few examples:

Note –

The last two examples are currently equivalent because the filters are applied only to your custom classes and Identity Manager classes.

If necessary, you can instrument other jars by modifying the following lines in build.xml as appropriate. For example,


<instrument todir="${lighthouse-dir-profiler}/WEB-INF" 
verbose="${instrumentor.verbose}" includeMethods="${profiler.includes}" 
excludeMethods="${profiler.excludes}">
           <fileset dir="${lighthouse-dir}/WEB-INF">
               <include name="lib/idm*.jar"/>
               <include name="classes/**/*.class"/>
           </fileset>
</instrument>

By default, the configuration includes all your custom classes and most Identity Manager classes. A number of Identity Manager classes are forcibly excluded— because enabling them would break the Profiler.

For example, classes from the workflow, forms, and XPRESS engines are excluded or the Profiler would produce an unintelligible snapshot when profiling Java and Identity Manager objects.

Note that Java filters provide much more filtering granularity than IDM Object Filters. Java instrumentation adds significant overhead to the execution time, which can drastically skew the profiling results. Because Identity Manager objects are interpreted rather than compiled, the instrumentation overhead is negligible. So for example, there is basically no reason to exclude workflow A and include workflow B, and so forth.

Note –

You cannot modify Java filters while the Profiler is running. You must stop the Profiler before changing Java filters.

Miscellaneous

The Miscellaneous tab provides the following options:

Working with the IDM Profiler View

The IDM Profiler view consists of the following areas:

Current Project Area

The Current Project area consists of a drop-down menu that lists all of your current projects. Use this menu to select the project you want to profile.

Controls Area

The Controls area contains four icons, as described in the following table:

Icon 

Name 

Purpose 

Figure showing the Start Identity Manager Profiler icon

Start Identity Manager Profiler 

Starts the Profiler and opens the Profiler Options dialog. 

Figure showing the Stop Identity Manager Profiler icon

Stop Identity Manager Profiler 

Stops the Profiler. 

Figure showing the Reset Collected Results icon

Reset Collected Results 

Resets all of the profile results you collected to this point. 

Figure showing the Modify Profiling icon

Modify Profiling 

Reopens the Profiler Options dialog so you can change any of the settings to modify your current profile results. 

Status Area

The Status area reports whether you are connected to the Host and provides Status information as the Profiler is starting up, running, and stopping.

Profiling Results Area

The Profiling Results area contains two icons, which are described in the following table:

Icon 

Name 

Purpose 

Figure showing the Start Identity Manager Profiler icon

Start Identity Manager Profiler 

Starts the Profiler and opens the Profiler Options dialog. 

Figure showing the Reset Collected Results icon

Reset Collected Results 

Resets all of the profile results you collected to this point. 

Saved Snapshots Area

The Saved Snapshots area provides a list of all saved snapshots.

Note –

Instructions for saving snapshots are provided in Saving a Snapshot.

In addition, you can use the following buttons to manage these snapshots:

Working with the Snapshot View

When you open a snapshot, the results display in the Snapshot View window, located on the upper right side of Identity Manager IDE.

A snapshot provides several views of your data, which are described in the following sections:

Call Tree View

Call Tree view consists of a tree table showing the call timing and invocation counts throughout your system.

This tree table contains three columns:

Hotspots View

Hotspots view provides a flattened list of nodes that shows aggregate call timings regardless of parent.

This view contains the following columns:

Back Traces View

Back Traces view provides an inverted call stack showing all the call chains from where each node was called.

You can use these statistics to answer the question— How much time would I save if I eliminated this particular call chain from this node?

You can access the Back Traces view from any of the other snapshot views by right-clicking a node (known as the root node) and selecting Show Back Traces from the pop-up menu.

Note –

The Time and Invocations data values mean something different in Back Traces view:

Callees View

Callees view provides an aggregate call tree for a node (known as the root node), regardless of its parent chain.

These statistics are helpful if you have a problem area that is called from many places throughout the master call tree and you want to see the overall profile for that node.

You can access the Callees view from any of the other snapshot views by right-clicking a node (known as the root node) and selecting Show Callees from the pop-up menu.

Note –

The Time and Invocations data values used in Callees view have the same meaning as those used in Call Tree view.

Using the Pop-Up Menu Options

Right-click any node in Call Tree view or in Hotspots view and a pop-up menu displays with the options described the following table:

Menu Options 

Description 

GoTo Source 

Select this option to view the XML source for a node that corresponds to a Java method, workflow, form, rule, or XPRESS. For detailed information about this view, see How the Profiler Locates and Manages Source.

Show Back Traces 

Select this option to access the Back Traces view. For detailed information about this view, see Back Traces View.

Show Callees 

Select this option to access the Callees view. For detailed information about this view, see Callees View.

Find In Hotspots 

Select this option to find a node in the Hotspots view. For detailed information about this view, see Hotspots View.

List Options -> Sort -> 

Select this option to 

  • None

  • Call Tree

  • Time

  • Invocations

  • Ascending

  • Descending

List Options -> Change Visible Columns 

Select this option to change the columns displayed in the Call Tree or Hotspots list. 

When the Change Visible Columns dialog displays, you can select one or more of the following options: 

  • Call Tree: Call Tree

  • Invocations: Invocations

  • Time: Time

Searching a Snapshot

Use the Search iconFigure showing the Search icon , located at the top of the Snapshot View window to search for nodes by name the Call Tree view or Hotspots tree.

Alternatively, right-click any node in Call Tree view or Hotspots view and select Find in Call Tree or Find in Hotspots (respectively) from the pop-up menu to search for a node.

Saving a Snapshot

The Profiler provides several options for saving a snapshot. See the following table for a description of these options:

Icon 

Name 

Purpose 

Figure showing the Start Identity Manager Profiler icon

Save the Snapshot in the Project icon (located at the top of the Snapshot View window) 

Saves the snapshot in the nbproject/private/idm-profiler directory of your project. Snapshots saved in your project are listed in the Saved Snapshots section of the Profiler view.

Figure showing the Stop Identity Manager Profiler icon

Save the Snapshot Externally icon (located at the top of the Snapshot View window) 

Saves a snapshot to an external, arbitrary location. 

Figure showing the Reset Collected Results icon

Save As button (located in the Saved Snapshots area) 

Saves a snapshot to an external, arbitrary location. 

Tutorial: Troubleshooting Performance Problems

Identity Manager provides a tutorial (profiler-tutorial.zip) to help you learn how to use the Profiler to troubleshoot forms, Java rules, workflows, and XPRESS.

Use the following steps to complete the tutorial.

ProcedureStep 1: Create an Identity Manager Project

  1. Select File -> New Project.

  2. When the New Project wizard displays, specify the following, and then click Next:

    1. In the Categories list, select Web to indicate what type of project you are creating.

    2. In the Projects list, select Identity Manager Project.

      Note –

      You must create a regular Identity Manager project for a fully featured development environment. Do not select the Identity Manager Project (Remote) option.

  3. Complete the following fields on the Name and Location panel, and then click Next:

    • Project Name: Enter Idm80 as the project name.

    • Project Location: Use the default location or specify a different location.

    • Project Folder: Use the default folder or specify a different folder.

  4. When the Identity Manager WAR File Location panel displays, enter the location of the Identity Manager 8.1 war file. Typically, unzipping this file creates an idm.war file in the same directory.

  5. Click Next to continue to the Repository Setup panel.

    You should not have to change the default settings on this panel, just click Finish. When you see the BUILD SUCCESSFUL message in the Identity Manager IDE Output window, you can extract the Profiler tutorial files. See Step 2: Unzip the Profiler Tutorial for instructions.

ProcedureStep 2: Unzip the Profiler Tutorial

  1. Unzip profiler-tutorial.zip in the project root. The extracted files include:

    <project root>/custom/WEB-INF/config/ProfilerTutorial1.xml
<project root>/custom/WEB-INF/config/ProfilerTutorial2.xml
<project root>/src/org/example/ProfilerTutorialExample.java
<project root>/PROFILER_TUTORIAL_README.txt

  2. Start the Profiler. Proceed to Step 3: Start the Profiler.

ProcedureStep 3: Start the Profiler

  1. Use the instructions provided in Before You Begin to increase the memory for your server and Netbeans JVM.

  2. Use any of the methods described in Overview to start the Profiler.

  3. When the Profiler Options dialog displays, you can specify profiling options.

  4. Continue to Step 4: Set the Profiler Options

    Note –

    For detailed information about all of the different Profiler options, see Specifying the Profiler Options.

ProcedureStep 4: Set the Profiler Options

For the purposes of this tutorial, specify the following Profiler options:

  1. On the Mode tab, select Java and IDM Objects to profile form, Java, rule, workflow, and XPRESS objects.

  2. Select the Java Filters tab.

    Use the following steps to disable all Identity Manager Java classes except your custom Java classes (in this case, org.example.ProfilerTutorialExample):

    1. Click New and a new, blank field appears at the bottom of the Filter column.

    2. Enter com.waveset.* into the new field, and then select the Exclude box.

    3. Click New again.

    4. Enter com.sun.idm.* into the new field, and then select the Exclude box.

  3. Click OK to run the Profiler.

    Note –

    The Profiler takes a few minutes to complete the first time you run it on a project or if you have recently performed a Clean Project action.

    When the Profiler finishes processing, you are prompted to Log In.

  4. Enter the password configurator, select the Remember Password box, and then click OK to continue.

  5. When the Identity Manager window displays, log in.

    Note –

    Typically, you should log in to Identity Manager as a different user instead of logging in as configurator again. You are already logged into the Profiler as configurator, and the Identity Manager session pool only allows one entry per user. Using multiple entries can result in the appearance of a broken session pool and might skew your profiling results for finer-grained performance problems.

    However, for this simple example the session pool is of no consequence so you can login as configurator/configurator.

  6. In Identity Manager, select Server Tasks -> Run Tasks, and then click ProfilerTutorialWorkflow1.

    The tutorial might take a few moments to respond.

  7. Although you could take a snapshot now; you are going to reset your results instead, run the Profiler, run it again, and then take a snapshot.

    Note –

    It is a best practice to run the Profiler a couple of times before taking a snapshot to be sure all the caches are primed, all the JSPs are compiled, and so forth.

    Running the Profiler several times enables you to focus on actual performance problems. The only exception to this practice is if you are having a problem populating the caches themselves.

    1. Return to the IDM Profiler view in the Identity Manager IDE. Click the Reset Collected Results icon in the Profiling Results section (or in the Controls section) to reset all of the results collected so far.

    2. In Identity Manager, select Server Tasks -> Run Tasks again, and click ProfilerTutorialWorkflow1.

    3. When the Process Diagram displays, return to the Identity Manager IDE and click Take Snapshot in the Profiling Results section.

  8. The Identity Manager IDE downloads your snapshot and displays the results on the right side of the window.

    This area is the Call Tree view. At the top of the Call Tree, you should see a /idm/task/taskLaunch.jsp with a time listed in the Time column. The time should indicate that the entire request took six+ seconds.

  9. Expand the /idm/task/taskLaunch.jsp node, and you can see that ProfilerTutorialWorkflow1 took six seconds.

  10. Expand the ProfilerTutorialWorkflow1 node. Note that activity2 took four seconds and activity1 took two seconds.

  11. Expand activity2.

    Note that action1 took two seconds and action2 took two seconds.

  12. Expand action1 and note that the <invoke> also took two seconds.

  13. Double-click the <invoke> to open ProfilerTutorialWorkflow1.xml and highlight the following line:


    <invoke name=’example’ class=’org.example.ProfilerTutorialExample’/>

    You should see that a call to the ProfilerTutorialExample method took two seconds.

    Note –

    You are actually browsing XML source that was captured in the snapshot, rather than source in the project. Snapshots are completely self-contained. (For more information, see How the Profiler Locates and Manages Source.)

  14. Select the CPU:<date><time> tab to return to your snapshot.

  15. Expand the <invoke> node, and note that the Profiler spent two seconds in the Java ProfilerTutorialExample.example() method.

  16. Double-click the method name to open the ProfilerTutorialExample.java source and highlight the following line:


    Thread.sleep(2000);

    There’s the problem! This method contains a two-second thread sleep.

  17. If you return to the Call Tree, you can see that all of the two second paths lead to this method. (You should see three paths; for a total of six seconds.)

  18. Select the Hotspots tab (located at the bottom of the Call Tree area) to open the Hotspots view. Notice that ProfilerTutorialExample.example() has a total self time of six seconds.

    (For more information about Hotspots, see Working with the Snapshot View.)

  19. Right-click ProfilerTutorialExample.example() and select Show Back Traces from the pop-up menu.

    A new Back Traces tab displays at the bottom of the area.

  20. Expand the ProfilerTutorialExample.example() node on the Back Traces tab to see that this method was called from three places, and that the method took two seconds when it was called from each place.

    (For more information about Back Traces, see Working with the Snapshot View.)

  21. Click the Save the snapshot in the project icon to save your snapshot and close it.

    If you check the Saved Snapshots section on the IDM Profiler tab, you should see your snapshot. (You might have to scroll down.)

  22. Select the saved snapshot, and then click Open to re-open it.

    Note –

    You can use the Save As button to save your snapshots externally and use the Load button to load a snapshot from outside your project.

  23. Close the snapshot again.

ProcedureStep 5: Profile a ManualAction Workflow

The next part of this tutorial illustrates how to profile a workflow ManualAction.

  1. In Identity Manager, select Server Tasks -> Run Tasks, and then click ProfilerTutorialWorkflow2.

    After a few moments, an empty form displays.

  2. Click Save and the process diagram displays.

  3. Select Server Tasks -> Run Tasks again.

  4. Return to the Identity Manager IDE IDM Profiler view and click the Reset Collected Results icon in the Profiling Results section.

  5. Now click ProfilerTutorialWorkflow2 in Identity Manager.

  6. When the blank form displays again, click Save.

  7. In the IDM Profiler view, click Take Snapshot.

    After a few seconds, a snapshot should display in the Call Tree area. You should see that /idm/task/workItemEdit.jsp took six+seconds. (This result corresponds to the manual action in the workflow.)

  8. Expand the /idm/task/workItemEdit.jsp node and note that running all Derivations in the ManualAction form took a total of six seconds.

  9. Expand the Derivation, displayNameForm, variables.dummy, and <block> nodes.

    You should see that the <block> took six seconds and, of that time, the Profiler spent two seconds in each of the three invokes to the ProfilerTutorialExample.example(). method.

  10. You can double-click <block> to view the source.

Online Help

This section contains documentation corrections for online help.