5.1 Portal Configuration Tasks

This section includes information about:

5.1.1 Caching Management

You can use the Caching page to manage various caches maintained by the Identity Manager User Application. The User Application employs these caches to store reusable, temporary data on the application server so it can optimize performance.

You have the ability to control these caches when necessary by flushing their contents and changing their configuration settings.

Flushing caches

The caches are named according to the subsystems that use them in the Identity Manager User Application. Normally, you don’t need to flush them yourself, because the User Application does that automatically based on how frequently their data is used or when the source data changes. However, if you have a specific need, you can manually flush selected caches or all caches.

  1. Go to the Caching page:

  2. In the Flush Cache section of the page, use the drop-down list to select a particular cache to flush (or select Flush all):

    The list of available caches is dynamic; it changes depending on what data is cached at the moment.

  3. Click Flush Cache.

Flushing the Directory Abstraction Layer Cache

The User Application’s directory abstraction layer also has a cache. The DirectoryAbstractLayerDefinitions cache stores abstraction layer definitions on the application server to optimize performance for all data model operations.

In a typical situation, the User Application automatically keeps the DirectoryAbstractLayerDefinitions cache synchronized with the abstraction layer definitions stored in the Identity Vault. But, if necessary, you can manually flush the DirectoryAbstractLayerDefinitions cache as described in Flushing caches to force the latest definitions to be loaded from the Identity Vault.

For more information on the User Application’s directory abstraction layer, see the Identity Manager User Application: Design Guide.

Flushing Caches in a Cluster

Cache flushing is supported in both clustered and non-clustered application server environments. If your application server is part of a cluster and you manually flush a cache, that cache is automatically flushed on every server in the cluster.

Configuring Cache Settings

You can use the Caching page to display and change cache configuration settings for a clustered or non-clustered application server environment. Your changes are saved immediately, but they don’t take effect until the next User Application restart.

HINT:To restart the User Application, you can reboot the application server; redeploy the application (if the WAR has been changed in some way); or force the application to restart (as described in your application server’s documentation).

How Caching Is Implemented

In the Identity Manager User Application, caching is implemented via JBoss Cache. JBoss Cache is an open source caching architecture that’s included with the JBoss Application Server but also runs on other application servers.

To learn more about JBoss Cache, go to www.jboss.org/products/jbosscache.

How Cache Settings Are Stored

Two levels of settings are available for controlling cache configuration: global, and local. Use these settings to customize the caching behavior of the Identity Manager User Application. Table 5-1 describes the cache configuration settings.

Table 5-1 Cache Configuration Settings

Level

Description

Global settings

Global settings are stored in a central location (the Identity Vault) so that multiple application servers can use the same setting values. For example, someone with a cluster of application servers would typically use global settings for the cluster configuration values.

To find the global settings in your Identity Vault, look for the following object under your Identity Manager User Application driver:


configuration.AppDefs.AppConfig

For example:


configuration.AppDefs.AppConfig.MyUserApplicationDriver.MyDriverSet.MyOrg

The XmlData attribute of the configuration object contains the global settings data.

Local setting

Local settings are stored separately on each application server so that an individual server can override the value of one or more global settings. For example, you might want to specify a local setting to remove an application server from the cluster specified in the global settings, or to reassign a server to a different cluster.

To find the local settings on your JBoss application server, look for the following file under your JBoss server configuration’s conf directory: sys-configuration-xmldata.xml, for example jboss/server/IDM/conf/sys-configuration-xmldata.xml.

To find the local settings on your WebSphere application server, look for the sys-configuration-xmldata.xml file at the location you specified in the extend.local.config.dir property that you set at installation.

If your server has local settings, that data is contained in this file. (If no local settings have been specified, the file won’t exist.)

You should think of global settings as the default values for every application server that uses a particular instance of the User Application driver. When you change a global setting, you are affecting each of those servers (at the next User Application restart), except for those cases where an individual server specifies a local override.

How Cache Settings Are Displayed

The Caching page displays the current cache settings (from the latest User Application restart). It also displays the corresponding global and local values of those settings, and lets you change them (for use at the next User Application restart).

The global settings always have values. The local settings are optional.

Basic Cache Settings

These cache settings apply to both clustered and non-clustered application servers.

To configure basic cache settings:

  1. Go to the Caching page.

  2. In the Cache Configuration section of the page, specify global or local values for the following settings, as appropriate:

    Setting

    What to do

    Lock Acquisition Timeout

    Specify the time interval (in milliseconds) that the cache waits for a lock to be acquired on an object. You might want to increase this setting if the User Application gets a lot of lock timeout exceptions in the application log. The default is 15000 ms.

    Wake Up Interval Seconds

    Specify the time interval (in seconds) that the cache eviction policy waits before waking up to do the following:

    • Process the evicted node events

    • Clean up the size limit and age-out nodes

    Eviction Policy Class

    Specify the classname for the cache eviction policy that you want to use. The default is the LRU eviction policy that JBoss Cache provides:

    
    org.jboss.cache.eviction.LRUPolicy
    

    If appropriate, you can change this to another eviction policy that JBoss Cache supports.

    To learn about supported eviction policies, go to www.jboss.org/products/jbosscache.

    Max Nodes

    Specify the maximum number of nodes allowed in the cache. For no limit, specify:

    0
    

    You can customize this setting for some cache holders. See Customizable Cache Holders.

    Time To Live Seconds

    Specify the time to idle (in seconds) before the node is swept away. For no limit, specify:

    
    0
    

    You can customize this setting for some cache holders. See Customizable Cache Holders.

    Max Age

    Specifies the number of seconds an entry should be allowed to stay in the cache holder since its creation time. For no time limit, specify:

    0
    

    This setting is only available for Customizable Cache Holders.

    These settings are required, which means that there must be a global value for each, and optionally a local value too.

    If you want to override the global value of a setting with a local value, select the Enable Local check box for that setting. Then specify the local value. (Make sure that all of your local values are valid. Otherwise, you won’t be able to save your changes.)

    NOTE:For those settings where Enable Local is deselected, any existing local values are deleted when you save.

  3. Click Save.

  4. When you’re ready for your saved settings to take effect, restart the User Application on the applicable application servers.

Customizable Cache Holders

You can customize the Max Nodes, Time To Live, and Max Age settings for some cache holders. The cache holders are listed in Table 5-2.

Table 5-2 Customizable Cache Holders

Cache Holder Name

Description

DirectoryAbstractionLayerDefinitions

Caches the Directory Abstraction Layer definitions to optimize performance for all data model operations. See Flushing the Directory Abstraction Layer Cache.

DirectoryService.ContainerCacheHolder

Caches containers in the directory layer. Containers are shared by many users and groups, and reading them from the directory layer involves both network communication (with the LDAP server) and object creation. By default, the cache is limited to 50 containers, and the LRUs have a default Time To Live (TTL) of 10 minutes. Depending on the directory topography in your enterprise, you might need to adjust the maximum number of nodes or the TTL if you find the performance is suffering because of queries to the LDAP server for container objects. Making settings too high in combination with a large number of usable containers can cause unneeded memory consumption and net lower performance from the server.

DirectoryService.DelProxyRuntimeServiceDelegate

Caches delegate assignments.

DirectoryService.DelProxyRuntimeService.Delegation

Caches user availability settings.

DirectoryService.DelProxyRuntimeService.Delegator

Caches the delegator entities.

DirectoryService.DelProxyRuntimeService.Proxy

Caches proxy assignments.

DirectoryService.GroupCacheHolder

Caches groups in the directory layer. Groups are often shared by many users, and reading them from the directory layer involves both network communication (with LDAP server) and object creation. By default, the cache is limited to 500 groups, and the LRUs have a default TTL of 10 minutes. Depending on the user/group topography in your enterprise, you might need to adjust the maximum number of nodes or the TTL if you find the performance is suffering because of queries to the LDAP server for groups objects. Settings that are too high, in combination with a large number of usable groups, can cause unneeded memory consumption, and net lower performance from the server.

DirectoryService.MemberhipCacheHolder

Caches the relationship between a user and a set of groups. Querying the set of groups a user belongs to can be a network and CPU intensive operation on the LDAP server, especially if dynamic groups are enabled. For this reason, relationships are cached with an expiration interval so that changes in the criteria for inclusion/exclusion in a group (such as time-based dynamic groups) are reflected. The default Max Age is five minutes. However, if you use dynamic groups which have a requirement for finer grained time control, then you can adjust the Max Age on this cache holder to be just below the minimum time your finest grained time based dynamic group requires. The lower this value is, the more times the user's groups are queried during a session. Setting a value too high keeps the user/group relationships in memory perhaps longer than the user's session needlessly consuming memory.

DirectoryService.RolesMembershipCacheHolder

Caches the application role membership list by role.

DirectoryService.TeamManagerRuntime.Team

Caches the application team instances and team provisioning requests.

DirectoryService.UserCacheHolder

Caches users in the directory layer. Reading users from the directory layer involves both network communication (with LDAP server) and object creation. By default, the cache is limited to 1000 users, and the LRUs have a default TTL of 10 minutes. Depending on the user topography in your enterprise, you might need to adjust the maximum number of nodes or the TTL if you find the performance is suffering because of queries to the LDAP server for user objects. Making settings too high combined with a large number of different users logging in can cause unneeded memory consumption, and net lower performance from the server.

GlobalCacheHolder

The general purpose cache holder. This configuration applies to all caches that are not customizable (that is, all cache holders not listed in this table.)

JUICE

Caches the resource bundles used by the user interface controls and DN display expression lookup results. Changing the setting of the cache holder has a performance impact for the DN display expression lookups because they are frequently used in the User Application. The low value should be at least 300 seconds, but a higher value than 900 seconds is ok. A lower value should be used if the customer is frequently changing the attributes that are used in the DN display expression

RoleManager.RolesCacheHolder

Caches user role memberships listed by user.

Workflow.Model.Process

Caches the provisioning process XML object structure.

Workflow.Model.Request

Caches the provisioning request XML object structure.

Workflow.Provisioning

Caches provisioning request instances that have not completed. The default maximum capacity for the LRU cache is 500. The capacity can be modified by clicking the Administration/Provisioning tab and choosing the Engine and Cluster settings. The Process Cache Maximum Capacity appears on this page. This cache reduces the memory footprint for workflow processing without compromising performance.

Cache Settings for Clusters

This section discusses how to configure caching when you run the Identity Manager User Application across a cluster of application servers.

In the Identity Manager User Application, cluster support for caching is implemented via JGroups. JGroups is an open-source clustering architecture that’s included with the JBoss Application Server but also runs on other application servers.

The User Application’s cluster consists of nodes on a network that run JGroups and use a common Group ID. By default, the Group ID provided for the User Application’s cluster is a UUID that looks like this:

c373e901aba5e8ee9966444553544200

The UUID helps ensure uniqueness, so that the Group ID of the User Application’s cluster doesn’t conflict with the Group IDs of other clusters in your environment. For instance, the JBoss Application Server itself uses several JGroups clusters and reserves associated names including the Group IDs DefaultPartition and Tomcat-Cluster for them.

To learn more about JGroups, go to www.jboss.org/products/jgroups.

How Caching Works with a Cluster

When you start the User Application, the application’s cluster configuration settings on the Caching page determine whether to participate in a cluster and invalidates cache changes in the other nodes in that cluster. If clustering is enabled, the User Application accomplishes this by sending cache entry invalidation messages to each node as changes occur.

Preparing to Use a Cluster

To use caching across a cluster:

  1. Set up your JGroups cluster. This involves using the User Application installation program to install the Identity Manager User Application to each application server in the cluster (see Section 2.7, Clustering).

  2. Enable the use of that cluster in the User Application’s cache configuration settings

    See Configuring Cache Settings for Clusters.

Configuring Cache Settings for Clusters

After you have a cluster ready to use, you can specify settings for the support of caching across that cluster.

  1. Go to the Caching page.

  2. In the Cluster Configuration section of the page, specify global or local values for the following settings, as appropriate:

    Setting

    What to do

    Cluster Enabled

    Select True to invalidate cache changes to the other nodes in the cluster specified by Group ID. If you don’t want to participate in a cluster, select False.

    Group ID

    Specify the Group ID of the JGroups cluster in which you want to participate. There’s no need to change the default Group ID that’s provided for the User Application’s cluster, unless you want to use a different cluster.

    The Group ID must be unique and must not match any of the known JBoss cluster names such as DefaultPartition and Tomcat-Cluster.

    HINT:To see the Group ID in logging messages, make sure that the level of the caching log ( com.sssw.fw.cachemgr) is set to Info or higher.

    Cluster Properties

    Specify the JGroups protocol stack for the cluster specified by Group ID. This setting is for experienced administrators who might need to adjust the cluster properties. Otherwise, you should not change the default protocol stack.

    To see the current cluster properties, click view.

    For details on the JGroups protocol stack, go to www.joss.org/wiki/Wiki.jsp?page=JGroups.

    If you want to override the global value of a setting with a local value, select the Enable Local check box for that setting. Then specify the local value.

    For those settings where Enable Local is unselected, any existing local values are deleted when you save.

    Make sure that all nodes in your cluster specify the same Group ID and Cluster Properties. To see these settings for a particular node, you must access the Identity Manager user interface running on that node—by browsing to the URL of the user interface on that server—and then display the Caching page there.

    If you need to use the TCP protocol instead of the default UDP protocol, see Specifying the User Application Cluster Group Caching Configuration.

  3. Click Save.

  4. When you’re ready for your saved settings to take effect, restart the User Application on the applicable application servers.

5.1.2 Driver Status

You can use the Driver Status pane to determine the expiration status of your driver.

Figure 5-1 Sample Driver Status for a “Trial” Driver

An Expiration Date value of No Expiration means that the driver has been started and is fully licensed or has not yet been started. If it has not been started, it might also be a trial driver. If there is an expiration date, then the driver is a trial driver and it has been started. The page itself describes what values of UNKNOWN mean.

5.1.3 LDAP Parameters

You can use the LDAP Parameters pane to:

  • Change the credentials used by the Identity Manager User Application when connecting to the Identity Vault (LDAP provider)

  • Change the credentials for the guest account, if your system is configured to use a specific guest account, rather than LDAP anonymous account.

  • View other LDAP properties of the Identity Manager User Application. The values of these settings are determined when you install the User Application.

The user interface displays different fields depending on how you configured the guest account during installation. If you specified a guest account, the user interface includes fields that let you update the credentials for that account. If you have configured your system to use the LDAP Public Anonymous account, the user interface displays this message: The application is configured to use public anonymous account. To use a specific guest account, enable the guest account using the ldap configuration tool.

To administer LDAP connection parameters:

  1. On the Application Configuration page, select LDAP Connection Parameters from the navigation menu on the left.

    The LDAP Connection Parameters panel displays:

  2. Examine and modify the settings, as appropriate. For details, see:Settings You Can Change.

  3. If you make changes that you want to apply, click Submit.

Settings You Can Change

On the LDAP Connection Parameters panel, you can modify settings for the credentials for:

  • The Identity Manager User Application whenever it connects to the Identity Vault (LDAP provider).

  • The guest account (if configured).

The initial values for the credentials are specified during installation. These installation values are written to the sys-configuration-xmldata file. If you make changes to these credentials via the Administration page, your changes are saved to the User Application’s database; they are not saved to the sys-configuration-xmldata file. After values are written to the database, the User Application no longer checks the values written to the sys-configuration-xmldata file. This means that you cannot use the configupdate utility to change the credentials because they are ignored. However, you can use configupdate to change the type of guest user (LDAP Guest or Public Anonymous Account).

Table 5-3 LDAP Parameters

Setting

What to do

Admin Username

Type the name of a user who has full administrator rights in the Identity Vault. The Identity Manager User Application needs to access the Identity Vault as an administrator in order to function.

It is typical to specify the Identity Vault’s root administrator as the LDAP connection username. The root administrator has full control over the tree, so you need not assign any special trustee rights.

For example:


cn=admin,o=myorg

If you specify some other user, you need to assign inheritable trustee rights to the properties [All Attributes Rights] and [Entry Rights] on your User Application driver.

NOTE:To avoid confusion, it is recommended that you do not specify the User Application’s User Application Administrator as the LDAP connection username. It is best to use separate accounts for these two different purposes.

Admin Password

and

Confirm Password

Type the password that is currently set for that username in the Identity Vault.

Guest Username

Type the guest user’s distinguished name

Confirm Guest Password

Type the password for the guest user.

If TLS is enabled for your LDAP server, you might encounter the following error when you update the Admin username and password: Unable to authenticate to LDAP Provider. Disable this error by disabling TLS via iManager.

5.1.4 Logging Configuration

You can use the Logging page to control the levels of logging messages you want the Identity Manager User Application to generate and specify whether those messages are sent to Novell® Audit.

The Identity Manager User Application implements logging by using log4j, an open-source logging package distributed by The Apache Software Foundation. By default, event messages are logged to both of the following:

  • The system console of the application server where the Identity Manager User Application is deployed

  • A log file on that application server, for example:

    jboss/server/IDM/log/server.log
    

This is a rolling log file; after it reaches a certain size, it rolls over to another file. If you have configured your environment to include Novell Audit, you have the option of logging event messages there as well. For details on configuring your logging environment and Novell Audit, see Section 3.0, Setting Up Logging.

About the Logs

The Logging page lists a variety of logs, each outputting event messages from a different part of the Identity Manager User Application. Each log has its own independent output level.

The log names are based on log4j conventions. You’ll see these log names in the event messages that are generated, indicating the context of the message output.

Table 5-4 lists and describes the logs.

Table 5-4 Identity Manager User Application Logs

Log Name

Description

com.novell

Parent of other Identity Manager User Application logs

com.novell.afw.portal.aggregation

Messages related to portal page processing

com.novell.afw.portal.persist

Messages related to the persistence of portal data (including portal pages and portlet registrations)

com.novell.afw.portal.portlet

Messages from the portal core portlets and accessory portlets

com.novell.afw.portal.util

Messages from the portal import/export and navigation portlets

com.novell.afw.portlet.consumer

Messages related to portlet rendering

com.novell.afw.portlet.core

Messages related to the core portlet API

com.novell.afw.portlet.persist

Messages related to the persistence of portlet data (including portlet preferences and setting values)

com.novell.afw.portlet.producer

Messages related to the registration and configuration of portlets within the portal

com.novell.afw.portlet.util

Messages related to utility code used by portlets

com.novell.afw.theme

Messages from the theme subsystem

com.novell.afw.util

Messages related to portal utility classes

com.novell.soa.af.impl

Messages from the approval flow (provisioning workflow) subsystem

com.novell.srvprv.apwa

Messages from the Requests & Approvals Web application (actions and tags)

com.novell.srvprv.impl.portlet.core

Messages from the core identity portlets and password portlets

com.novell.srvprv.impl.portlet.util

Messages from the identity-related utility portlets

com.novell.srvprv.impl.servlet

Messages from the UI control framework’s ajax servlet and ajax services

com.novell.srvprv.impl.uictrl

Messages from the UI control registry API and approval form rendering

com.novell.srvprv.impl.vdata

Messages from the directory abstraction layer

com.novell.srvprv.spi

Messages from the UI control registry API

com.sssw.fw.cachemgr

Messages related to the framework cache subsystem

com.sssw.fw.core

Messages related to the framework core subsystem

com.sssw.fw.directory

Messages related to the framework directory subsystem

com.sssw.fw.event

Messages related to the framework event subsystem

com.sssw.fw.factory

Messages related to the framework factory subsystem

com.sssw.fw.persist

Messages related to the framework persistence subsystem

com.sssw.fw.resource

Messages related to the framework resource subsystem

com.sssw.fw.security

Messages related to the framework security subsystem

com.sssw.fw.server

Messages related to the framework server subsystem

com.sssw.fw.servlet

Messages related to the framework servlet subsystem

com.sssw.fw.session

Messages related to the framework session subsystem

com.sssw.fw.usermgr

Messages related to the framework user subsystem

com.sssw.fw.util

Messages related to the framework utility subsystem

com.sssw.portal.manager

Messages related to the Portal Manager

com.sssw.portal.persist

Messages related to portal persistence

The User Application logs are hierarchical. For example, com.novell is the parent of other logs underneath it. Any additional logs inherit its properties.

Changing Log Levels

You can control the amount of information that is written to a particular log by changing the level that is set for it. By default, all logs are set to Info, which is an intermediate level.

  1. Go to the Logging page:

  2. At the top of the page, find a log whose level you want to change.

  3. Use the drop-down list to select one of the following levels:

    Level

    Description

    Fatal

    The least detail. Writes fatal errors to the log.

    Error

    Writes errors (plus all of the above) to the log.

    Warn

    Writes warnings (plus all of the above) to the log.

    Info

    Writes informational messages (plus all of the above) to the log.

    Debug

    Writes debugging information (plus all of the above) to the log.

    Trace

    The most detail. Writes tracing information (plus all of the above) to the log.

  4. Repeat Step 2 and Step 3 for other logs, as needed.

  5. Click Submit.

    You can change the log level for all of the logs to one setting by selecting Change log level of all above logs and using the drop-down list to select the level.

Adding Logs for Other Packages

You can add logs for other packages used by the User Application.

  1. Go to the Logging page:

  2. At the bottom of the page, select Add Log Level for Package, then use the drop-down list to select the package.

  3. Choose a log level from the drop-down, then click Submit.

Sending Log Messages to Novell Audit

You can use the Logging page to control whether the Identity Manager User Application sends event message output to Novell Audit. Novell Audit logging is off by default, unless you turn it on when installing the User Application.

To toggle Novell Audit logging on/off:

  1. Go to the Logging page.

  2. Select or deselect the following setting, as appropriate: Also send logging messages to Audit.

  3. Click Submit.

Persisting Your Log Settings

By default, changes you make on the Logging page stay in effect until the next application-server restart or User Application redeployment. After that, the log settings revert to their default values.

However, the Logging page does offer you the option of persisting your changes to its settings. If you turn on this feature, values for the log settings are stored in a logging configuration file on the application server where the Identity Manager User Application is deployed. For example:

  • On JBoss, this file is

    jboss/server/IDM/conf/idmuserapp_logging.xml
    
  • On WebSphere, this file is specified according to the custom property named idmuserapp.logging.config.dir.

To toggle persistence of settings on or off:

  1. Go to the Logging page.

  2. Select or deselect the following setting, as appropriate: Persist the logging changes

  3. Click Submit.

5.1.5 Portal Settings

You can use the Portal page to view characteristics of the Identity Manager User Application.The settings are for informational purposes and cannot be changed.The values of these settings are set in the User Application WAR. ( Default Theme reflects your current theme choice from the Themes page.)

5.1.6 Theme Administration

You can use the Themes page to control the look and feel of the Identity Manager user interface.

A theme is a set of visual characteristics that apply to the entire user interface (including the guest and login pages, the Identity Self-Service tab, the Requests & Approvals tab, and the Administration tab). There’s always just one theme in effect for the user interface. The Themes page offers a choice of several themes, in case you want to switch to a different one.

The Themes page also enables you to:

  • Preview each theme choice to see how it looks

  • Customize any theme choice to reflect your own branding (such as a logo)

Previewing a Theme

Before choosing a theme, you can preview how it will change the look of the Identity Manager user interface.

  1. Go to the Themes page:

  2. Find a theme that you are interested in, then click the corresponding Preview button.

    The preview for that theme displays in a new browser window:

  3. Scroll through the preview to see the characteristics of this theme.

  4. When you’re done, click Close Preview Page (in the top left corner) or close the preview window manually.

Choosing a Theme

When you find a theme that you like, you can choose to make it the current theme for the Identity Manager user interface.

  1. Go to the Themes page.

  2. Click the radio button for the theme you want.

  3. Click the Save button.

    The look of the user interface changes to reflect your chosen theme.

Customizing a Theme's Branding

You can tailor any theme by substituting your own images and changing some color settings. This enables you to give the Identity Manager user interface a custom look to meet the branding requirements of your company or organization.

  1. Go to the Themes page.

  2. Find a theme that you want to customize, then click the corresponding Customize button.

    The Themes page displays the Customize Branding settings for that theme:

  3. Specify your customizations by changing the settings in one or more tabs (as needed). Each tab contains the settings for different parts of the User Application interface. They include:

    • General: Lets you specify general theming properties such as a favorites icon, background, link and hover color, and the left navigation area properties.

    • Header: Lets you specify the header color, texture, logo and username properties.

    • Header tabs: Lets you specify the properties for the header tabs.

    • Admin subnavigation: Lets you specify the properties for the Admin tab.

    • Login: Lets you specify the properties for the login screen.

    Follow the on-screen instructions for specifying each setting. The changes are not reflected in the User Application until you save them. If you have made unsaved changes, the Save button displays an asterisk * to indicate that the changes are pending a save.

  4. Click Save.

    If you’re editing the current theme, the look of the user interface changes to reflect your customizations. If you want to undo all of your customizations to the theme, click the Reset button.

  5. When you’re done working on this theme, click Back to Theme Selector.

Defining a Custom Theme

You can also create and deploy your own custom themes and deploy them in their own WAR file. When they are deployed, the custom themes are available through the Themes management page of the Administration tab. Before attempting to create your own custom theme, make sure you have a working knowledge of the following technologies:

  • The structure of J2EE WAR files, how to modify the contents of a WAR file, and how to deploy one to your application server.

  • How to modify CSS and XML files

  • How to create the graphic elements for your theme

Creating a Custom Theme

To create a custom theme, begin with a copy of an existing theme (such as BlueGloss) from the User Application WAR:

  1. Back up the deployed User Application WAR file ( IDMProv.WAR) to the directory in which you install, for example the /opt/novell/idm subdirectory.

  2. In a test environment, extract the contents of the User Application WAR file.

    The files that comprise the User Application’s themes are located in the resource\themes subdirectory. Each theme resides in its own directory with an appropriate name.

  3. In the test environment, create a directory for the custom theme.

    The directory name can be any valid directory name, but it should reflect the name of the theme, and it should not contain spaces.

  4. Copy the contents of the BlueGloss theme from the extracted WAR file to the new subdirectory. You will be working with the following files:

    File Name

    Description

    theme.xml

    The theme descriptor file. It includes entries for display name and description. They are used in the Themes page of the Administration tab. The remaining entries correspond to the brandable selectors. The width and height attributes on these entries are used in the branding page to reference the exact dimensions needed when a user uploads a customized version of these images. These entries must match their respective images, width and height as found in the themes.css.

    theme.css

    Contains the CSS selectors used to style the look and feel of the user interface.

    print.css

    Contains the CSS selectors used to style a print friendly version of the user interface.

    An images subdirectory

    Contains the images used by the theme.

    Rules for working with these files:

    • Do not change the names of the theme.xml, theme.css, and print.css files.

    • The CSS Selector names must remain the same, but you can change the properties of the selectors to establish the look and feel.

    • The images subdirectory can have any name, but you must reference it correctly in the CSS and XML files.

  5. Make your changes to the images, CSS style sheets and other theme elements as needed. The following changes are recommended:

    • In the theme.xml file:

      • display-name: Change this to a value that represents your theme. It displays as the Theme-name in the Themes page of the User Application’s Administration tab.

      • description: Change this to a value that describes your theme. It displays as the Description in the Themes page of the User Application’s Administration tab.

      • Consider whether to localize the display-name and Description fields.

    • In the graphics directory:

      • thumbnails.gif: Replace the copy with your own image. This image displays along with the Theme-name and Description of the theme (described above) that is shown in the Themes page of the Administration tab. It typically illustrates what the User Application landing page looks like when the associated theme is applied

      • Renaming graphics files: If you change the names of graphics files (rather than just substituting a different image of the same name), make sure to change the reference to the image in both the theme.xml and the theme.css file. If the image is not used in the branding interface (for example, if it is not listed as one of the subset of brandable images in the theme.xml file), then you will only need to change the reference to the image in the theme.css file. Suppose you want to rename images/header_left.gif to images/my_company_name.gif. Edit the theme.css file to reflect the new image name.

  6. After you make all of the desired changes to the theme files, add your customized theme directory to a new WAR file that contains one or more custom themes. Deploy the new WAR to your test application server. Testing tip: Open the Themes page (available under the Administration tab). Your theme should display along with the prepackaged themes. Use the Theme Preview action to see how the customized changes to your new theme will render. This is a useful way to ensure that you have completed all of your intended changes to your theme.

  7. After your changes are fully tested, you can deploy the WAR containing the custom theme to your production application server.

Any number of custom themes can reside in a single WAR. Any number of custom WARs containing custom themes can be deployed.

To undeploy the theme, remove the WAR that contains the theme from the application server’s deploy directory. Before undeploying, make sure that any themes it contains are not defined as the User Application’s default theme. If you remove the WAR and it does contain the default theme, the Theme Administration screen displays an error message and reverts the User Application theme to the original default theme defined at installation time.

Customizing the Theme for External Password WAR

If you configured Password Management to use an External Password WAR, the theme for the Forgot Password page is defined in that external password WAR. The default name for the external password WAR is IDMPwdMgt.WAR. The IDMPwdMgt.WAR contains one theme; by default, it is BlueGloss. It does not include a user interface for modifying or branding this theme.

You can define a custom theme for the external Forgot Password page. The procedure for defining a custom theme is described in Defining a Custom Theme; however, the deployment procedure for the external Forgot Password page is different and the rules about the custom theme WAR are more restrictive. After you define the custom theme:

  • Package the theme in a WAR named IDMPwdMgtTheme.WAR.

  • The IDMPwdMgtTheme.WAR can contain a single theme, and the theme must be located in the resource/themes/Theme directory within the WAR.

  • Deploy the IDMPwdMgtTheme.WAR on the application server where the external WAR is located. Only one custom theme can be deployed at a time.