Customizing The Console

The Access Manager Legacy mode console uses JSP and CSS to define the look and feel of the pages used to generate its frames. A majority of the content is generated dynamically—based on where, and at what, the user is looking. In that regard, the modification of the content is somewhat restricted. Within the Navigation frame, the layout of the controls (the view menu), the action buttons, and the table with current objects in each JSP can be changed. In the Data frame, the content displayed is dynamically generated based on the XML service file being accessed but the layout, colors, and fonts are controlled by the adminstyle.css style sheet.

The Default Console Files

An administrator can modify the console by changing tags in the JSPs and CSS's. All of these files can be found in the AccessManager-base/SUNWam/web-src/applications/console directory. The files in this directory provide the default Sun Java System interface. Out of the box, it contains the following subdirectories:

• base contains JSP that are not service-specific.

• css contains the adminstyle.css which defines styles for the console.

• federation contains JSP related to the Federation Management module.

• html contains miscellaneous HTML files.

• images contains images referenced by the JSP.

• js contains JavaScript^TM files.

• policy contains JSP related to the Policy Service.

• service contains JSP related to the Service Management module.

• session contains JSP related to the Current Sessions (session management) module.

• user contains JSP related to the Identity Management module.

Console-related JSP contain HTML and custom library tags. The tags are defined in tag library descriptor files (.tld) found in the AccessManager-base/SUNWam/web-src/WEB-INF directory. Each custom tag corresponds to a view component in its view bean. While the tags in the JSP can be removed, new tags can not be added. For more information, see the Sun Java System Application Framework documentation.

Creating Custom Organization Files

To customize the console for use by a specific organization, the AccessManager-base/SUNWam/web-src/applications/console directory should first be copied, renamed and placed on the same level as the default directory. The files in this new directory can then be modified as needed.

There is no standard to follow when naming the new directory. The new name can be any arbitrarily chosen value.

For example, customized console files for the organization dc=new_org, dc=com might be found in the AccessManager-base/SUNWam/web-src/applications/custom_directory directory.

To Create Custom Organization Files

1. Change to the directory where the default templates are stored:

   cd AccessManager-base/SUNWam/web-src/applications

2. Make a new directory at that level.

   The directory name can be any arbitrary value. For this example, it is named AccessManager-base/SUNWam/web-src/applications/custom_directory/.

3. Copy all the JSP files from the console directory into the new directory.

   AccessManager-base/SUNWam/web-src/applications/console contains the default JSP for Access Manager. Ensure that any image files are also copied into the new directory.

4. Customize the files in the new directory.

   Modify any of the files in the new directory to reflect the needs of the specific organization.

5. Modify the AMBase.jsp file.

   In our example, this file is found in AccessManager-base/SUNWam/web-src/applications/custom_directory/base. The line String console = "../console"; needs to be changed to String console = "../new_directory_name ";. The String consoleImages tag also needs to be changed to reflect a new image directory, if applicable. The contents of this file are copied in Creating Custom Organization Files.

   <!-- Copyright © 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. --> <% String console = "../console"; String consoleUrl = console + "/"; String consoleImages = consoleUrl + "images"; %>

6. Change the value of the JSP Directory Name attribute in the Administration Service to match that of the directory created in Creating Custom Organization Files.

   The JSP Directory Name attribute points the Authentication Service to the directory which contains an organization’s customized console interface. Using the console itself, display the services registered to the organization for which the console changes will be displayed. If the Administration Service is not visible, it will need to be registered. For information on registering services, see the Administration Guide.

   Once the new set of console files have been modified, the user would need to log into the organization where they were made in order to see any changes. Elaborating on our example, if changes are made to the JSP located in the AccessManager-base/SUNWam/web-src/applications/custom_directory directory, the user would need to login to that organization using the URL:

   http:// server_name.domain_name:port//
   		service_deploy_uri/UI/Login?org=
   			custom_directory_organization.

Alternate Customization Procedure

The console can also be modified by simply replacing the default images in AccessManager-base/SUNWam/web-src/applications/console/images , with new, similarly named images.

Miscellaneous Customizations

Included in this section are procedures for several specific customizations available to administrators of the Access Manager console.

To Modify The Service Configuration Display

A service is a group of attributes that are managed together by the Access Manager console. Out-of-the-box, Access Manager loads a number of services it uses to manage its own features. For example, the configuration parameters of the Logging Service are displayed and managed in the Access Manager console, while code implementations within Access Manager use the attribute values to run the service.

To Modify The User Profile View

The Access Manager console creates a default User Service view based on information defined in the amUser.xml service file.

A modified user profile view with functionality more appropriate to the organization’s environment can be defined by creating a new ViewBean and/or a new JSP. For example, an organization might want User attributes to be formatted differently than the default vertical listing provided. Another customization option might be to break up complex attributes into smaller ones. Currently, the server names are listed in one text field as:

protocol://Access Manager_host. domain:port

Instead, the display can be customized with three text fields:

protocol_chooser_field://server_host_field :port_number_field

A third customization option might be to add JavaScript to the ViewBean to dynamically update attribute values based on other defined input. The custom JSP would be placed in the following directory: AccessManager-base/SUNWam/web-src/applications/console/user. The ViewBean is placed in the classpath com.iplanet.am.console.user. The value of the attribute User Profile Display Class in the Administration Service (iplanet-am-admin-console-user- profile-class in the amAdminConsole.xml service file) would then be changed to the name of the newly created ViewBean. The default value of this attribute is com.iplanet.am.console.user.UMUserProfileViewBean.

Display Options For The User Profile Page

There are a number of attributes in the Administration Service that can be selected to display certain objects on the User Profile page. Display User’s Roles, Display User’s Groups and User Profile Display Options specify whether to display the roles assigned to a user, the groups to which a user is a member and the schema attributes, respectively. More information on these service attributes can be found in the Administration Guide.

To Localize The Console

All textual resource strings used in the console interface can be found in the amAdminModuleMsgs.properties file, located in AccessManager-base/SUNWam/locale/. The default language is English (en_US). Modifying this file with messages in a foreign language will localize the console.

To Display Service Attributes

Service attributes are defined in XML service files based on the sms.dtd . In order for a particular service attribute to be displayed in the console, it must be configured with the any XML attribute. The any attribute specifies whether the service attribute for which it is defined will display in the Access Manager console.

To Customize Interface Colors

All the colors of the console are configurable using the Access Manager style sheet adminstyle.css located in the AccessManager-base/SUNWam/web-src/applications/console/css directory. For instance, to change the background color for the navigation frame, modify the BODY.navFrame tag; or to change the background color for the data frame, modify the BODY.dataFrame. The tags take either a text value for standard colors (blue, green, red, yellow, etc.) or a hexadecimal value (#ff0000, #aadd22, etc.). Replacing the default with another value will change the background color of the respective frame after the page is reloaded in the browser. Miscellaneous Customizations details the tag in adminstyle.css.

Example 2–1 BODY.navFrame Portion of adminstyle.css

BODY.navFrame   {
                color: black;
                background: #ffffff;
                }


                  

To Change The Default Attribute Display Elements

The console auto-generates Data frame pages based on the definition of a service’s attributes in an XML service definition file. Each service attribute is defined with the XML attributes type, uitype and syntax. Type specifies the kind of value the attribute will take. uitype specifies the HTML element displayed by the console. syntax defines the format of the value. The values of these attributes can be mixed and matched to alter the HTML element used by the console to display the values of the attributes. For example, by default, an attribute of the single_choice type displays its choices as a drop down list in which only one choice can be selected. This list can also be presented as a set of radio buttons if the value of the uitype attribute is changed to radio. Miscellaneous Customizations illustrates this concept.

Example 2–2 uitype XML Attribute Sample

 <AttributeSchema name="test-attribute"
                    type="single_choice"
                    syntax="string"
                    any="display"
                    uitype="radio"
                    i18nKey="d105">
                    <ChoiceValues>
 <ChoiceValue i18nKey="u200">Daily</ChoiceValue>
 <ChoiceValue i18nKey="u201">Weekly</ChoiceValue>
 <ChoiceValue i18nKey="u202">Monthly</ChoiceValue>
                    </ChoiceValues>
                    <DefaultValues>
                        <Value>Daily</Value>
                    </DefaultValues>
                </AttributeSchema>


                  

Miscellaneous Customizations is a listing of the possible values for each attribute, and the corresponding HTML element that each will display based on the different groupings.

To Add A Module Tab

The section “Plug-In Modules” mentions the capability to plug-in external applications as modules. Once this is accomplished, the module needs to be accessible via the console by adding a new module tab. Label information for module tabs are found in the amAdminModuleMsgs.properties console properties file located in AccessManager-base/SUNWam/locale/. To add label information for a new module, add a key and value pair similar to module105_NewTab=My New Tab. Miscellaneous Customizations illustrates the default pairs in the file.

Example 2–3 Module Tab Key And Value Pairs

module101_identity=Identity Management
module102_service=Service Configuration
module103_session=Current Sessions
module104_federation=Federation Management


                  

The module name and a URL for the external application also need to be added to the View Menu Entries attribute in the Administration Service (or iplanet-am-admin-console-view-menu in the amAdminConsole.xml service file). When a module tab in the Header frame is clicked, this defined URL is displayed in the Navigation frame. For example, to define the display information for the tab sample, an entry similar to module105_NewTab|/amconsole/custom_directory /custom_NavPage would be added to the View Menu Entries attribute in the Administration Service.

The console retrieves all the entries from this attribute and sorts them by i18n key. This determines the tab display order in the Header frame.

After making these changes and restarting Access Manager, a new tab will be displayed with the name My New Tab.

To Display Container Objects

In order to create and manage LDAP organizational units (referred to as containers in the console), the following attributes need to be enabled (separately or together) in the Administration Service.

• Display Containers In Menu—Containers are organizational units as viewed using the Access Manager console. If this option is selected, the menu choice Containers will be displayed in the View menu for top-level Organizations, Sub-Organizations and other containers.

• Show People Containers—People containers are organizational units containing user profiles. If this option is selected, the menu choice People Containers will be displayed in the View menu for Organizations, Containers and Sub-Organizations.

• Show Group Containers—Group containers are organizational units containing groups. If this option is selected, the menu choice Group Containers will be displayed in the View menu for Organizations, Containers and Group Containers.

Viewing any of these display options is also dependent on whether the Enable User Management attribute is selected in the Administration Service. (This attribute is enabled by default after a new installation.) More information on these attributes can be found in the Administration Guide.