2 Designing the GUI with PresentationXML

The Identity System combines XSL (eXtensible Style Language) stylesheets and XML (eXtensible Markup Language) data to dynamically create almost all of the pages presented to its users. This capability, called PresentationXML, provides Oracle Access Manager developers with a great deal of design flexibility and avoids the necessity of providing many pages of static HTML content along with the product.

Within the bounds described in this chapter, you can use this feature yourself to customize Identity System user application presentation to suit your own needs. For example, you can:

• Apply your organization's color schemes and other graphical style elements such as fonts, button images, and logos, to Oracle Access Manager pages.

• Add, modify, or remove particular functions on an Identity System page.

• Add hidden information which could be used by the Identity Event Plug-in API (see the Oracle Access Manager Deployment Guide).

• Create entirely new pages and functionality.

This chapter tells you how to use PresentationXML and includes the following topics:

• PresentationXML Operation

• Setting Up Your Environment to Customize the Stylesheets

• PresentationXML Components

• PresentationXML Libraries—Provides a listing and description of some major parts of the full library of PresentationXML components.

• Customizing Oracle Access Manager—Provides an outline of one method for doing customization.

• Customizing the Identity System Pages—Gives an example you can complete to gain first-hand experience with customizing Oracle Access Manager.

• Verifying XSL Files

Note:

Prior experience with XSL and XML is not essential to using PresentationXML. However, you must understand them as you delve into more complex kinds of changes. Some reference sites and brief syntax introduction are provided in Appendix A, "XML Background".

Note:

Prior experience with XSL and XML is not essential to using PresentationXML. However, you must understand them as you delve into more complex kinds of changes. Some reference sites and brief syntax introduction are provided in Appendix A, "XML Background".

The System Administration Console always uses the default, Classic Style.

2.1 PresentationXML Operation

This section describes how standard PresentationXML operates, introduces some parameters that can be used to control its output, and describes a useful alternate mode of operation. The terms you see include:

Stylesheet: This term identifies XSL stylesheets that describe how data sent over the Web is to be presented to the user.

Base Stylesheet: This term refers to several Identity System stylesheets that provide a foundation for other stylesheets:

• basic.xsl

• font.xsl

• searchform.xsl

• navbar.xsl

• title.xsl

Wrapper: This term identifies an XSL stylesheet file that contains only XSL include statements with pointers to other files.

See also:

For more information, see "PresentationXML Components" and "Styles".

2.1.1 Stylesheet Encoding

This discussion outlines the encoding schemes you see in XSL stylesheet files, and what to specify if you customize these files.

XML must start with the following string:

<?xml version="1.0"?>

Release 10.1.4 supports two encoding formats for requests: ISO-8859-1 (Latin-1) and UTF-8. The response, however, is in UTF-8 encoding only.

Within this required string you can use a tag to select an encoding specification.

In new 10.1.4 installations, use the UTF-8 encoding tag (encoding="UTF-8"), as follows.

<?xml version="1.0" encoding="UTF-8" ?>

For backward compatibility with older plug-ins in an upgraded environment, use the Latin-1 encoding tag (encoding="ISO-8859-1"). For example:

<?xml version="1.0" encoding="ISO-8859-1" ?>

ISO-8859-1 Encoding: For pure English text, there is no difference between ISO-8859-1 encoding and UTF-8 encoding. For this reason, the encoding scheme for English language XSL files remains ISO-8859-1 in most if not all wrapper files in the \lang\langtag\style0 directory.

The following example shows an XSL stylesheet wrapper (style.xsl), which is the same in all language directories: English (\lang\en-us), German (\lang\de-de), Japanese (\lang\ja-jp) and so on. The only difference in these files is the language designation specified by the langtag item in the last line of this example, which differs from country to country (language to language):

\IdentityServer_install_dir\identity\oblix\lang\langtag\style0\style.xsl

<?xml version="1.0" encoding="ISO-8859-1" ?> - <!--  Copyright (c) 1996-2005, Oracle All Rights Reserved.  --> - <xsl:stylesheet version="1.0"
   xmlns:xsl="http://www.w3.org/1999/XSL/Transform"   
   xmlns:oblix="http://www.oblix.com/">  <xsl:variable name="styleName">style0/</xsl:variable>   <xsl:variable name="localeName">langtag</xsl:variable> 
...

UTF-8 Encoding: To enable multibyte character support, you can explicitly define the encoding to be UTF-8. Without the encoding string, the default encoding specification is UTF-8. In global stylesheets, for example, there is no encoding specified and the default is UTF-8 as follows (\IdentityServer_install_dir\\identity\oblix\lang\shared\style.xsl):

<?xml version="1.0" 
<!--   Copyright (c) 1996-2005, Oracle All Rights Reserved.    --> 
<xsl:stylesheet version="1.0" 
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
xmlns:oblix="http://www.oblix.com/">
<xsl:variable name="styleName">style0</xsl:variable>
<xsl:variable name="localeName">en-us</xsl:variable>
<xsl:variable name="gifPathName">../../../lang/<xsl:value-of 
select="$localeName"/>/<xsl:value-of select="$styleName"/></xsl:variable>
<xsl:variable name="jsPathName">../../../lang/shared</xsl:variable>
</xsl:stylesheet>

Note:

When customizing XML and XSL files, you can choose either encoding="ISO-8859-1" or encoding="UTF-8". In either case, the Oracle Access Manager XML parser reads the encoding tag in the file for correct processing.

2.1.2 Server-Side Processing

The diagram on the next page shows the default data flow for PresentationXML. This default process, called server-side processing, generates HTML and presents it to the browser. The following steps are performed.

Process overview: Server-side processing

1. The browser sends a request to the URL of a Web server that includes the WebPass plug-in.

   The full URL contains the location of the Web server and implicitly the application, such as the Group Manager, that is expected to service the request. The URL also usually includes information telling the application what task to perform and providing parameters that direct the task. (See more on the full syntax for the URL in "Identity System Applications".)

2. WebPass takes the request, makes a few minor changes to it, and passes it to the Identity Server.

3. The Identity Server passes the request to the appropriate application. (For the sake of clarity, the diagram shows the application as if it were a separate entity, but it is actually a dynamically loaded part of the Identity Server.)

4. The application processes the request and creates an XML file named OutputXML.

   OutputXML contains information that appears as part of the final HTML. The application also opens its registration file to get the name of the base XSL stylesheet that applies to the request that it has just satisfied, as illustrated in Figure 2-1.

   Figure 2-1 Identity Server Passing a Request to an Application

   
   

5. The OutputXML and the name of the base stylesheet are returned to the Identity Server.

6. The Identity Server reads the text of the base stylesheet from the library. This text usually includes references to other stylesheets, which are used in common by many different types of requests. For each reference, the Identity Server reads the additional text from the stylesheet library and inserts it in-line in place of the reference, making one large stylesheet.

7. An XSLT (XSL transformer) application is part of the Identity Server. The XSLT parses and interprets the stylesheet and combines it with the OutputXML to create HTML. The OutputXML content provides a basis for the decisions that are made as the stylesheet is interpreted and also provides data to be included in the HTML.

8. When the entire stylesheet has been processed, the resulting HTML is sent to WebPass, which returns it to the browser.

9. The browser uses WebPass to obtain GIF images and JavaScripts as needed.

2.1.3 Parameters that Control Operation

You can append various parameters that control format, xsl, and style, to the URL to shape the way the XSLT works with the OutPutXML and the stylesheets.

2.1.3.1 Format Parameter

The format parameter can be used to control the way in which the Identity Server combines the OutputXML and the stylesheet before the resulting information is passed to the browser, if this is allowed by the setting of the outputFormat parameter in the globalparams.xml parameter file. See Table B-9 for details.

The Identity Server checks the value that was provided for the outputFormat parameter in this file. The parameter must be set to Default in the parameter file to enable use of the format parameter here in the PresentationXML URL.

The format parameter takes one of three values

• Default: If the parameter is not included in the URL XSLT processing is done at

• format=xmlnoxsl: The Identity Server returns the Output XML without doing XSLT processing; that is, the XSL stylesheet is not applied. This is a good way to generate the OutputXML. If you do this, and want to capture the result, save the displayed data as XML (if your browser supports this). The true OutputXML contains escaped characters that are lost if you save the displayed data as a text file.

  Note:

  If the same CGI is used to handle different functionality, just appending "&format=xmlnoxsl" to the URL would result in executing the default functionality of a given CGI.

  If the same CGI is used to handle different functionality, you need a way to re-submit the form request with "&format=xmlnoxsl" as part of the action. This can be achieved using the following methods.

  • Method 1: Append "&format=xmlnoxsl" to the form action within the relevant .xsl stylesheets. While this might seem straight-forward enough, be aware that you are making changes to a stylesheet and this could have unintended consequences. After making the change, you must either restart the Identity Server or update the globalparams.xml file to disable stylesheet caching (for example, set stylesheet caching to 1) and allow stylesheet dynamic-change updates.

  • Method 2: Rewrite the POST request as a GET request, and add &format=xmlnoxsl. One way of rewriting the POST request as a GET request is to use a portal insert. See "Customizing Portal Inserts" for details.

    It is not always possible to tell directly what parameters are being passed to the POST request.

    Sometimes the action is a JavaScript that rewrites the form parameters before the form request gets submitted. In such instances, you might want to run a packet sniffer to capture the POST request as it is leaving the browser. Alternatively, you can enable debugging on the Identity Server and look at the request data. However, you might have to sift through a certain amount of non-relevant data. You then recreate the POST request as a GET request because it is easier to submit as one URL. In some rare cases, the POST data is too long and does not fit as a GET request, so you can write an HTML static form and manually fill-in the data from the POST request captured with the sniffer or from the Oracle Access Manager debug log.

    Note:

    Oracle has found certain packet sniffers useful. For example, daSniff available at http://demosten.com/dasniff offers a command-line interface and requires the WinPcap libraryavailable at http://netgroup-serv.polito.it/winpcap.

• format=xml: The Identity Server returns the Output XML, with the name of the base XSL stylesheet embedded as an XML element. For this to be useful, the browser must be able to do its own XSLT processing. In that case the browser sends requests to WebPass for the content of included stylesheets, and WebPass gets them directly from the appropriate library.

The only browser currently able to do its own XSLT processing is Microsoft's Internet Explorer (IE). IE Versions 5.5 and later are compatible with PresentationXML.

Earlier versions of IE use an earlier proposed version of XSLT, based on a working draft from 1998. This is inconsistent with the current version of XSLT, which Oracle Access Manager follows. To use the format=xml option with the earlier versions of IE, you must either rewrite the XSL stylesheet to be consistent with the earlier draft version or download Microsoft's patch to its XSLT processor.

See also:

See Appendix A, "XML Background" for a discussion of how to download and install the patch.

2.1.3.2 XSLProcessor

When using IdentityXML, the XSLProcessor parameter indicates the processor to use when generating the page.

The value default is the only officially supported value. This value indicates that the XDK processor should be used. The other processor types, XALAN and DGXT should be used only in non-production environments for testing XSL processor issues.

2.1.3.3 XSL Parameter

The xsl parameter determines which XSL stylesheet is to be combined with the OutPutXML. It can take either of two values:

• Default: If the parameter is not included in the URL, the default is to apply the XSL stylesheet specified in the registration file.

• xsl=stylesheet_name: Use the specified stylesheet as the base stylesheet, in place of the one specified in the Registration File.

2.1.3.4 Style Parameter

The style parameter indicates which style directory in the library to get the base stylesheet from. (For an explanation of styles, see "Styles".) Once the style parameter has been used in the URL, the style you chose is implicitly included in all further requests in the session for that particular browser.

• Default: If the parameter is not included in the URL, the default is to either: get the base stylesheet from the style0 directory (if the style parameter has not been previously used), or continue to get the base stylesheet from the style directory specified by a previous use of the style parameter).

• style=styledirectoryname: Get the base stylesheet from the specified style directory, and continue to do so for the rest of the session with this browser.

Note:

Administrators can create new style directories and set them as the default style. In the current discussion, style0 stands for the default style directory.

2.1.4 Client-Side Processing

The diagram on the following page shows the major alternative method for using PresentationXML. This method is called client-side processing, because it presumes that the browser generates its own HTML, given the OutPutXML and the base stylesheet. To set this up, you use the format=xml parameter as discussed earlier. In this case, the only responsibility of the Identity Server is to pass the OutPutXML, with the name of the base stylesheet embedded, through WebPass back to the browser. The browser then sends requests to WebPass for various library components as it needs them.

Process overview: Client-side processing

1. The browser sends a request to the Web server, as in server-side processing.

2. WebPass takes the request, makes a few minor changes to it, and passes it to the Identity Server, as before.

3. The Identity Server passes the request to the appropriate application, as before.

4. The application processes the request, creates an OutPutXML file, and retrieves the base stylesheet, as before.

5. The OutputXML and base stylesheet are returned to the Identity Server, as before.

6. However, the Identity Server does no processing of the OutPutXML. Instead, it embeds the base stylesheet name into the OutPutXML and sends the result to Webpass, which passes it the browser.

7. The browser then makes requests to the Web server, as needed, for the referenced stylesheets, images and JavaScripts, as illustrated in Figure 2-2.

   Figure 2-2 Browser Making Requests to the Web Server

   
   

2.1.5 Caching Considerations

For the sake of efficiency, the Identity System maintains a cache of stylesheets, converted to a binary format. Stylesheets can be changed while the Identity System is running, but must be forced into this cache in order to take effect. One way to do this is to stop and start the Identity Server.

Another way is to use the XSL stylesheet control parameters provided (page 211) in the globalparams.xml parameter file:

Identity_install_dir\identity\oblix\apps\common\bin\globalparams.xml

where Identity_install_dir is the directory where the Identity Server is installed.

There are two of these:

• XSLStylesheetLiveUpdate: The default value for this parameter is false, which means, if the stylesheet is cached, the Identity System uses the cached binary version regardless of any changes to the original file. In a production environment, this parameter should be set to false. Setting it to true causes Oracle Access Manager to compare file stamps to see if the stylesheet has been modified in between requests. This is not desirable in a production system because it is an unnecessary overhead.

  Changing the value to true causes a check of the timestamp of the text version of the file against the timestamp for the cached version. If the cached version is older, the text file is converted to binary and replaces the older version in the cache. Note, however, that this works only for base stylesheets.

• XSLStylesheetCacheSize: Default value for this parameter is 200. In a development environment, you can change the value to 1 so that only one stylesheet can be cached (0 is not a legal value). Go forward one page, then return to the one you are testing. This works for stylesheets at all levels.

  Recommendation: In a production environment, the XSLStylesheetCacheSize parameter should be at least equal to or greater than the number of base stylesheets. The value of this should be greater than 200. To optimize performance, you should also set the XSLStyleSheetLiveUpdate parameter to false.

2.2 Setting Up Your Environment to Customize the Stylesheets

To prepare for customizing the PresentationXML stylesheets, you want to be able to preview the effect that updated stylesheets have on the user interface. To be able to preview your changes, you must set up an XML editor and create local versions of Identity application XML files. This section discusses these topics, including a discussion of setting up the XMLSpy editor. You can use XMLSpy to test changes that you make to the stylesheets. XMLSpy is an XML development environment that enables you to transform XML documents according to definitions in XSL stylesheets.

The procedures in this section are appropriate for users who are new to XMLSpy. If you have more experience with it and with PresentationXML, you can modify the steps as needed.

The following task overview summarizes the steps to generating the XSL files that you want to customize.

Task overview: Setting up your environment to test stylesheet customizations

1. Make local copies of your PresentationXML folders and add them to an XML editing environment.

   See "To configure PresentationXML folders in XMLSpy" for details.

2. Configure PresentationXML image folders.

   See "To configure IdentityXML image folders for local testing" for details.

3. Import the XML that you want to customize using the stylesheets.

   See "To import an Identity System XML file to work with its respective XSL stylesheet" for details.

4. Transform the XML file with the XSL stylesheet.

   See "To transform the XML file to XSL" for details.

To configure PresentationXML folders in XMLSpy

1. Create a folder named Presentation XML, for example:

   c:\PresentationXML

   This is your working folder. You can copy the XSL for the Identity Server and WebPass, and the images into this folder.

2. Create two sub-folders under the one that you created in the previous step named "identity" and "webcomponent".

   c:\PresentationXML\identity\

   c:\PresentationXML\webcomponent

3. Copy the identity stylesheets folder from the Web server into the "identity" folder.

   Copy from:

   IdentityServer_install_dir\identity\oblix\lang

   To:

   c:\PresentationXML\identity\

   The resulting directory structure should be similar to the following:

   C:\PresentationXML
         identity
              lang
                  en-us\. . .
                  shared\. . .
         webcomponent
   

4. For the WebPass stylesheets, copy the entire WebComponent stylesheets folder, with its subdirectories, from the Web server where WebPass is installed into the webcomponent folder that you created, as follows:

   Copy from:

   WebPass_install_dir\webcomponent\oblix\lang

   To:

   C:\PresentationXML\webcomponent\

5. The resulting directory structure should be similar to the following:

   C:\PresentationXML
         identity
              lang
                  en-us\. . .
                  shared\. . .
         webcomponent
              lang
                  en-us\. . .
                  shared\. . .
   

6. Launch XMLSpy.

7. To start a new project, click Project, then click New Project.

8. In the XMLSpy Project pane, right-click the XSL Files folder and select Add External Folder.

9. Browse to the following location, select the identity folder, and click OK:

   C:\PresentationXML\identity

10. Repeat the previous step for the webcomponent folder.

To configure IdentityXML image folders for local testing

1. In XMLSpy, modify the path to the images and javascript files.

   This is required because there is a common reference to all images when running on a Web server, but not on your local drive.

   In XMLSpy or a text editor, open the following style.xsl file:

   C:\PresentationXML\identity\lang\en-us\style0

2. Change the gifPathName on line 8 as follows:

   From:

   ../../../lang

   To:

   C:\PresentationXML\webcomponent\lang\shared

3. Change the jsPathName in line 9 as follows:

   From:

   ../../../lang/shared

   To:

   C:\PresentationXML\webcomponent\lang\shared

To import an Identity System XML file to work with its respective XSL stylesheet

1. Go to the Identity System function that you want to customize.

   For example in the Identity System, click User Manager, then click My Identity.

2. Append the following to the URL string used for this page:

   &format=xmlnoxsl

3. Press Enter or Go.

   As illustrated in Figure 2-3, the profile page is shown as raw XML.

   Figure 2-3 Profile Page Represented as Raw XML

   
   

4. In your browser, save this information as a file by clicking File, then clicking Save As and providing a file name, for example, viewProfile.xml.

5. Create a folder for storing the XML files that you created using the &format=xmlnoxsl parameter, for example:

   C:\PresentationXML\xml

6. In XMLSpy, to add the XML folder that you created in the previous step, right-click the XML Files folder, click Add External Folder, browse for the XML folder, and click OK.

7. In XMLSpy, expand the XML Files folder in the Project pane and double-click the file that you want to transform.

   The file contents appear in the right pane.

To transform the XML file to XSL

1. In XMLSpy, click XSL/XQuery, then click XSL Transformation.

2. Browse the XSL stylesheets, for example, to transform the My Identity page, you would navigate to the following:

   C:\PresentationXML\identity\lang\en-us\style0\usc_profile.xsl

3. Click Open.

4. Click OK.

   After a minute, the HTML output based on the transformation of the XML and XSL appears.

5. Modify the XSL file as described in the following sections and test the changes in XMLSpy.

2.3 PresentationXML Components

This section describes the Identity System components that work together to create PresentationXML. These components are:

XSL Transformer: In addition to transferring data between WebPass and the applications, the Identity Server is usually responsible for transforming the OutPutXML (using the stylesheet as a guide) into HTML for use by the browser. To accomplish this, the Identity Server contains a built-in XSL Transformer. See "XSL Transformer" for details.

Applications: The functional entities within the Identity Server, such as the User Manager or Lost Password Management, that handle the logic specific to each request. See "Identity System Applications" for details.

URLs: The location information, and other parameters, that the browser provides in order to make a request through WebPass to reach a specific application. See "URLs" for details.

Output XML: The stream of XML data created by each Identity System application. This can be captured as a file. It contains the information to be shown on the requested page. See "OutPutXML" for details.

XML Schemas: Files that describe the type and hierarchy of data that appears in the OutPutXML. See "XML Schemas" for details.

Registration files: Files that specify which stylesheets to use and which XML schema file describes the OutPutXML. See "Registration Files" for details.

JavaScripts: JavaScript applications which perform specialized tasks. Pointers to these are provided within the HTML. See "JavaScripts" for details.

Styles: Collections of data that support the generation of the HTML for the page. For each application, the data includes:

• Stylesheets: Files containing XSL instructions which tell the XSL transformer how to use the information provided in the OutPutXML. See "XSL Stylesheet Content" for details.

• Images: Small graphic files referenced in the HTML, which are combined to make the final GUI presentation. See "Images" for details.

2.3.1 XSL Transformer

The Identity Server contains a built in XSL Transformer. The Transformer follows the logic provided in an XSL stylesheet and creates a file of text following an HTML format. The Transformer uses the content of the OutPutXML to determine branches at decision points in its logic and to get content for data to be included in the HTML.

2.3.2 Identity System Applications

PresentationXML supports six applications, which are dynamically loaded and then executed from within the Identity Server. The following table lists the applications and shows the name for each application. The browser provides a URL as part of its request to the Identity Server and the application name appears as a string within the URL. The application name also appears as a directory name, under which the PresentationXML data for the particular application can be found (see "Directory Structure" for details). Descriptions of each application and details for using each one are provided in the Oracle Access Manager Introduction.

Application	Application Name
Group Manager	groupservcenter
Organization Manager	objservcenter
User Manager	userservcenter
Lost Password Management	lost_pwd_mgmt
Query Builder	querybuilder
Selector	selector

There is an additional legal value which is used in URLs for activities that are common across applications:

Application	Application Name
Resources used across applications	common

2.3.3 URLs

URLs that the browser provides to the Identity Server are of two basic kinds. First is the URL for the first page of each application, the one you arrive at after logging in. An example is the front page URL for User Manager:

http://www.thedomain.com/identity/oblix/apps/userservcenter/bin/userservcenter.cgi

This can be divided into several parts. The first part is:

http://www.thedomain.com/

which is the location of the server site to which the Identity Server has been added as a plug-in. The second part:

http://www.thedomain.com/identity/oblix/

tells the server site that you want to work with the Identity Server. The third part is:

apps/userservcenter/bin/userservcenter.cgi

which tells the Identity server which of its applications, in this case the User Manager, you want to work with.

Formally, as discussed in the specification Internet RFC 2396- Uniform Resource Identifiers (URI): Generic Syntax, the following string:

identity/oblix/apps/userservcenter/bin/userservcenter.cgi

is a path to an application that can be executed.

Table 2-0 shows the path to the first page URL for each application:

Table 2-1 URL to the First Page for Each Application

Application	Application Front Page URL
Group Manager	identity/oblix/apps/groupservcenter/ bin/groupservcenter.cgi
Organization Manager	identity/oblix/apps/objservcenter/bin/objservcenter.cgi
User Manager	identity/oblix/apps/userservcenter/bin/userservcenter.cgi
Lost Password Management	identity/oblix/apps/lost_pwd_mgmt/bin/lost_pwd_mgmt.cgi
Query Builder	identity/oblix/apps/querybuilder/bin/ querybuilder.cgi
Selector	identity/oblix/apps/selector/bin/ selector.cgi

The front page in turn contains links to other pages in the application. The URL for such a link could resemble the following:

http://www.thedomain.com/identity/oblix/                                              apps/   userservcenter/bin/
userservcenter.cgi                                              ?program=view                                              &uid=cn%3DJohn%20Smith%2C%20ou%3DCorporate
%2C%20ou%3DCompany%2C%20c%3DUS                                            &tab_id=Employees

This an extension of the content of the front page URL. The information that locates the server and specifies the application to use are as they were before. Added are several parameters, set off by the ? and & delimiters.

For PresentationXML, the most significant parameter is program, which identifies the purpose of the requested page. The program name serves as a lookup index in a registration file for each application.

See Also:

• Chapter 3, "Customizing Portal Inserts" for URL parameters.

• "Registration Files" for information on registration files.

2.3.4 OutPutXML

OutPutXML is a structured stream of information which contains the content of a page to be created by using Presentation XML. The arrangement of this content and the choice as to how much of it appears on the final page is determined by the stylesheet that is applied to it.

Each application generates an OutPutXML stream matching the task that it is performing. The content of this stream varies significantly with the directory content that the application is working with.

The detailed content of the OutPutXML is therefore not predictable. However, it is possible to predict the kinds of data that an OutPutXML stream contains, because this data conforms to XML schemas which Oracle Access Manager follows for each application.

Given the application and the program name, you can locate the corresponding schema file name in the application's registration file.

2.3.5 XML Schemas

The OutPutXML information generated by each program within each Identity System application is hard-coded and is not directly changeable by users. The content of the OutPutXML is not controlled by the content of the XML schema file. The file is provided only as a developer's aid, to help you design XSL stylesheets to work with the OutPutXML. XML schema files follow a standard developed by the World Wide Web Consortium. See "XML Schema" for the standard, and an introduction to XML syntax.

Note:

XML schema files do not have any effect on the PresentationXML and are located only on WebPass. Oracle recommends that you not change any of the XML schema files.

Here is an example XML schema file, the complete usc_profile.xsd file, located in WebPass_install_dir\identity\oblix\WebServices\XMLSchema\usc_profile.xsd:

<?xml version="1.0" encoding="UTF-8"?>
<!-- edited with XMLSPY v5 rel. 3 U (http://www.xmlspy.com) by zzz (zzz) -->
<xsd:schema 
      targetNamespace="http://www.oblix.com/"  
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.oblix.com/"
elementFormDefault="qualified">
   <xsd:include schemaLocation="component_profile.xsd"/>
</xsd:schema>

The line in bold beginning with xsd:include indicates that there is more information to be included in-line in this schema definition, in the file at:

../..//XMLSchema/component_profile.xsd.

2.3.5.1 component_profile.xsd

The complete content of the component_profile.xsd file follows. Notice that this file includes pointers to four other schema files, such as navbar.xsd:

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema targetNamespace="http://www.oblix.com/" xmlns:xsd="http:// www.w3.org/2001/XMLSchema" xmlns="http://www.oblix.com/" elementFormDefault="qualified">
   <xsd:include schemaLocation="navbar.xsd"/>
   <xsd:include schemaLocation="searchform.xsd"/>
   <xsd:include schemaLocation="component_panel.xsd"/>
   <xsd:include schemaLocation="component_basic.xsd"/>
   <xsd:element name="ObProfile">
      <xsd:complexType>
         <xsd:sequence>
            <xsd:element ref="ObPanel" minOccurs="0" maxOccurs="unbounded"/>
            <xsd:element ref="ObHeaderPanel" minOccurs="0"/>
            <xsd:element ref="ObRequestInfo" minOccurs="0"/>
            <xsd:element ref="ObScripts" minOccurs="0"/>
            <xsd:element ref="ObForm" minOccurs="0"/>
            <xsd:element ref="ObDisplay" minOccurs="0"/>
            <xsd:element ref="ObTextMessage" minOccurs="0" maxOccurs="unbounded"/>
            <xsd:element ref="ObSelectorInfoForm" minOccurs="0"/>
            <xsd:element ref="ObButton" minOccurs="0" maxOccurs="unbounded"/>
            <xsd:element ref="ObStatus" minOccurs="0"/>
         </xsd:sequence>
      </xsd:complexType>
   </xsd:element>
   <xsd:element name="Oblix">
      <xsd:complexType>
         <xsd:sequence>
            <xsd:choice>
               <xsd:element ref="ObProfile"/>
               <xsd:element ref="ObError"/>
            </xsd:choice>
            <xsd:element ref="ObNavbar" minOccurs="0"/>
            <xsd:element ref="ObSearchForm" minOccurs="0"/>
            <xsd:element ref="ObApplicationFunc" minOccurs="0"/>
            <xsd:element ref="ObStatus" minOccurs="0"/>
         </xsd:sequence>
         <xsd:attribute name="oblang" type="xsd:string"/> 
      </xsd:complexType>
   </xsd:element>
</xsd:schema>

This file is representative of most of the XML schema files in that:

• It begins with a set of included XML schemas, ones that are used in common across several applications.

• The lines starting with <xsd:element name="ObProfile"> and ending with </xsd:element> define an element called ObProfile.

• The lines in between, starting with <xsd:element ref= indicate that the ObProfile element contains the nested elements ObPanel, ObHeaderPanel, and so on.

Note:

ObProfile in turn is referenced as part of the Oblix element, which is the root element of the entire Oracle Access Manager schema. The root element is the starting point for the application of the XSL stylesheet.

2.3.5.2 Schema Files

XML schema files do not have any effect on the PresentationXML and are located only on WebPass.

The following are some of the most often used schema files:

• navbar.xsd: Defines the Navigation Bar, which is the top two lines of each page, including the application name, help and logout buttons, and the various tabs to select other applications or modules within the application.

• searchform.xsd: Defines the Search Form line, which is the row of graphics shown on some pages, that starts with the graphic labeled search. This row might have other rows beneath it.

• component_panel.xsd: Defines the content for profiles, the sets of descriptive information for users, groups or organizations.

• component_basic.xsd: Defines many of the lowest level elements, and includes displaytype.xsd and error.xsd.

• displaytype.xsd: Defines formatting for each of the Identity System display types.

• error.xsd: Defines the ObError element.

Each of these files contains other nested elements, and so on. For easy reference, tables giving the names of the most commonly used schema files, the names of the elements contained within them, and a brief description of what each element is, are provided in the "XML Schema Elements Library".

Note:

The OutPutXML information generated by each program within each Identity System application is hard-coded and is not directly changeable by users. The content of the OutPutXML is not controlled by the content of the XML schema file. The file is provided only as a developer's aid, to help you design XSL stylesheets to work with the OutPutXML. Users should not change any of the XML schema files.

2.3.6 Registration Files

Each of the Identity System applications has associated with it a unique registration file. This is a text file holding information arranged as a series of XML elements. Using the ObProgram name that appears in the URL for a lookup index, the specific Identity application searches its registration file to get the name of the base stylesheet that is to be applied to the OutPutXML. As an aid to the developer, the registration file also holds the name of the XML schema that describes the OutPutXML for the program.

Table 2-0 shows the path to the registration file for each application.

Table 2-2 Path to the Registration File for Each Application

Application	Registration File Location
Group Manager	Identity_install_dir\identity\oblix\apps\ groupservcenter\bin\groupservcenterreg.xml
Organization Manager	Identity_install_dir\identity\oblix\apps\ objservcenter\bin\objservcenterreg.xml
User Manager	Identity_install_dir\identity\oblix\apps\ userservcenter\bin\userservcenterreg.xml
Lost Password Management	Identity_install_dir\identity\oblix\apps\lost_pwd_mgmt\bin\lostpwdmgmtreg.xml
Query Builder	Identity_install_dir\identity\oblix\apps\ querybuilder\bin\querybuilderreg.xml
Selector	Identity_install_dir\identity\oblix\apps\selector\ bin\selectorreg.xml

The main applications also frequently call logic from the common resource applications. When this happens the application looks for the appropriate stylesheet in the common registration file:

Application	Application Name
Common resources	Identity_install_dir\identity\oblix\common\bin\ oblixbasereg.xml

2.3.6.1 General Content of Registration Files

Registration files have the following general content. In the following example, key variable values within each registration file are indicated in italic text. Structural elements in the following example appear in bold.

<?xml version="1.0"?>
<ObProgramRegistry>
 <ObApplication name="application_name">
   <ObProgram name="a_program_name">
     <ObStyleSheet name="stylesheetname.xsl"/>
     <ObSchema name="Its_XML_schema_name.xsd"/>
   </ObProgram>
   <ObProgram name="a_program_name">
      <ObButton name="a_button_name"/>
         <ObButton name="another_button_name"/>
         <ObButton name="yet_another_button_name"/>
         <ObButton name="maybe_more_button_names"/>
         <ObStyleSheet name="stylesheetname.xsl"/>
         <ObSchema name="XML_schema_name.xsd"/>
   </ObProgram>
   <ObProgram name="and_so_on">
         ...
   </ObProgram>
         ...
 </ObApplication>
</ObProgramRegistry>

Each of these elements serves a particular purpose.

For example, the following element identifies the file as a registration file:

<ObProgramRegistry>

while the following element identifies the application to which this registration file applies:

<ObApplication name="the_application_name">

For example:

<ObApplication name="groupservcenter">

The program name identifies the program, or function, within the application, to which the stylesheet, buttons and schema apply:

<ObProgram name="a_program_name">

For example:

<ObProgram name="commonNavBar">

The stylesheet name identifies the base stylesheet that is associated with the program specified by ObProgram.

<ObStyleSheet name="stylesheetname.xsl"/>

For example:

<ObStyleSheet name="gsc_front.xsl"/>

The following element identifies the XML schema file that is associated with the program specified by ObProgram:

<ObSchema name="XML_schema_name.xsd"/>

For example:

<ObSchema name="gsc_front.xsd"/>

Note:

There is only one ObStyleSheet element and only one ObSchema element for each ObProgram element.

The following element identifies an ObButton element that is associated with the program specified by ObProgram. There might be anywhere from zero to many ObButton elements for each ObProgram element:

<ObButton name="a_button_name"/>

For example, in the program name for save, the first button is:

<ObButton name="groupSubscribe"/>

An ObButton is an Oracle Access Manager-specific construct that packages a graphic, mouseover text, and link as a unit to be built into the page.

You cannot change the content of the named button package that is provided in the Output XML. You can, however, remove the entry for the button from the registration file, in which case it does not appear in the finished page. And you can control where and whether the button is displayed using the XSL stylesheet.

Caution:

Oracle recommends that only experienced developers consider editing the registration file. Use extreme care if you decide to edit a registration file.

2.3.6.2 Excerpt: User Manager Registration File

Following is an excerpt from the User Manager registration file in Identity_install_dir\identity\oblix\apps\userservcenter\bin\userservcenterreg.xml with information for the view program highlighted in bold.

Note:

The XML schema file name that applies to the OutPutXML data for the view program is usc_profile.xsd and the stylesheet file to be used is usc_profile.xsl. In fact, the usc_profile.xsl stylesheet is used by several functions. For details about this stylesheet, "XSL Stylesheet Content".

<?xml version="1.0"?>
<ObProgramRegistry>
 <ObApplication name="userservcenter">
      <ObProgram name="front">
      <ObStyleSheet name="usc_profile.xsl" /> 
             <ObSchema name="usc_front.xsd" /> 
         </ObProgram>
         <ObProgram name="commonNavbar">
             <ObStyleSheet name="usc_profile.xsl" /> 
             <ObSchema name="usc_front.xsd" /> 
         </ObProgram>
      ...
      <ObProgram name="deactivateUserArchive">
      <ObStyleSheetname=
         "Deactuser_purgearchiveconfirm.xsl"/>
      <ObButton name="wfArchivePurgeBack"/>
      <ObSchema name="usc_deactivateUserPurge.xsd"/>
      </ObProgram>
      <ObProgram name="view">
         <ObStyleSheet name="usc_profile.xsl"/>
         <ObButton name="initiateDeactivateUser"/>
         <ObButton name="userreactivate"/>
         <ObButton name="userModify"/>
         <ObSchema name="usc_profile.xsd"/>
      </ObProgram>
      <ObProgram name="modify">
         <ObStyleSheet name="usc_profile.xsl"/>
      <ObButton name="userSaveChange"/>
         <ObButton name="userCancelChange"/>
         <ObSchema name="usc_profile.xsd"/>
      </ObProgram>
      ...
   </ObApplication>
</ObProgramRegistry>

2.3.7 JavaScripts

Because the JavaScripts are supplied by WebPass in direct response to requests from the browser, they are located in directories associated with WebPass, rather than with the Identity Server. For example:

WebPass_install_dir\identity\oblix\lang\shared

For more information, see "Directory Structure".

HTML created by PresentationXML has embedded within it references to JavaScript files and functions within the files. A few of these files are associated with specific applications, but most of them are provided under WebPass.

A list of some of the most important of these files, and functions available within them, is provided at "JavaScript Library".

2.3.8 Styles

The manner in which Oracle Access Manager presents information, its style, is a direct result of the appearance of the graphical images used and the way in which they are combined on the page. Stylesheets control the way in which the images are combined. The images themselves can be changed, or different image names can be used in the stylesheets.

Note that for particularly complex stylesheets, the transformation engine can run out of stack space. If you run into this issue, you can modify the value of the StringStack parameter in the globalparams.xml file. See "Oracle Access Manager Parameter Files" for details.

2.3.8.1 New Stylesheet Structure

Messages in stylesheets depend upon a language. With multiple-language capability, messages have been brought out of the stylesheets and defined separately as variables in msgctlg.xsl (and msgctlg.js for JavaScript files). For details about message catalogs, See"Changing Message Catalogs and MouseOver Text".

In addition, each stylesheet has a corresponding language-specific thin wrapper in:

Identity_install_dir\identity\oblix\lang\langTag\style0

Each wrapper in \style0 includes the main language-neutral stylesheet stored in \shared:

Identity_install_dir\identity\oblix\lang\shared

The purpose of this new thin wrapper is to segregate the main functionality of the stylesheet template, which is language independent, from language-specific messages in the stylesheets.

Example: basic.xsl wrapper stylesheet

For example a typical wrapper stylesheet, basic.xsl, is located in the language-specific \style0 directory, and can also be in a custom style directory that was created for your site:

Identity_install_dir \identity\oblix\lang\en-us\style0\basic.xsl

Identity_install_dir \identity\oblix\lang\en-us\Custom\basic.xsl

The following example shows basic.xsl content:

<?xml version="1.0" ?> 
- <!--    Copyright (c) 1996-2005, Oracle Inc. All Rights Reserved.  --> 
- <xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
  xmlns:oblix="http://www.oblix.com/">
  <xsl:include href="./style.xsl" /> 
  <xsl:include href="../msgctlg.xsl" /> 
  <xsl:include href="../../shared/basic.xsl" /> 
  </xsl:stylesheet>

The basic.xsl wrapper stylesheet includes a pointer to:

• msgctlg.xsl, one directory up from your custom directory (in identity\oblix\lang\en-us)

• style.xsl file in your custom directory

  Due to the change in location of all image files, a new gifPathName variable is defined in style.xsl. For more information, see "Images".

• basic.xsl in identity\oblix\lang\shared.

  \shared contains default global stylesheets that are language-neutral. \style0 contains corresponding default thin wrapper files, which are language specific. A language-specific \style0 directory exists for each installed language. Typically, these language-specific wrappers call the global stylesheet in \shared.

See also "XSL Stylesheet Content".

2.3.8.2 XSL Stylesheet Content

XSL stylesheets follow a standard developed by the World Wide Web Consortium. See "XSL Validation" for information on the standard, and an introduction to XSL syntax.

As discussed earlier, PresentationXML uses the name of the current program as an index to its registration file, to get the name of an associated XSL stylesheet. For example, if the User Manager application is running the view program, then it locates and uses the usc_profile.xsl file as its stylesheet.

The following is partial content of the User Manager usc_profile.xsl stylesheet file. The information is shown in a compressed format in which each occurrence of <xsl:template represents many lines of XSL which for the sake of clarity are not shown here:

<?xml version="1.0" ?> 
<!-- Copyright ... -->
<xsl:stylesheet version="1.0"
   xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
   xmlns:oblix="http://www.oblix.com/">
<xsl:include href=./basic.xsl" />
<xsl:include href=./selectorinfo.xsl" />
<xsl:include href=./usc_searchform.xsl" /> 
<xsl:include href=./usc_navbar.xsl" /> 
<xsl:template match="/">
...
<xsl:template match="oblix:ObProfile"> ...
<xsl:template match="oblix:ObProfile/Oblix/ObForm"> ...
<xsl:template match="/oblix:Oblix/oblix:WfActorComment">
<xsl:template match="oblix:WfActorComment/oblix:ObForm">
<xsl:template match="oblix:ObHeaderPanel">...
<xsl:template match="oblix:ObPanel">...
<xsl:template match="oblix:ObAttribute"> ...
<xsl:template name ="horizontalButton"> ...
</xsl:stylesheet>

The lines beginning with xsl:template match are the top level of a great many lines of XSL instructions, called a template, which tell the XSL Transformer how to build the output page.

For example, the line:

<xsl:template match="oblix:ObProfile">

in effect tells the transformer to look for an occurrence of the oblix:ObProfile element in the OutPutXML and, if it finds it, to begin to apply the instructions following this line in the stylesheet.

In the case of this example stylesheet, building of the HTML begins with the line <xsl:template match="/">. Within that template, the Navigation Bar and the Search Form are built. The remaining templates go on to build the Profile information, including the Header Panel (the one including the user photo) and each of the other panels.

The lines beginning with xsl:include, shown in bold, indicate other XSL files which are to be added in-line to generate the complete XSL stylesheet. These included files can contain references to other included files, and so on. Certain base stylesheet files are used in common by almost all of the applications.

Base stylesheets include:

• basic.xsl: Contains templates to define attributes and status, and to control display information. It also contains references to the font.xsl and title.xsl files.

• searchform.xsl: Contains templates to create the Searchform line.

• navbar.xsl: Contains templates to create the Navigation Bar.

• font.xsl: Contains templates to define HTML size, fonts and colors for recurring text such as page headings.

• title.xsl: Contains the default titles for the HTML pages.

Each base stylesheet includes other nested stylesheets, and so on. For easy reference, tables giving the names of the most commonly used stylesheets, the names of the templates contained within them, and a brief description of what each template does, are provided in "Stylesheets".

See also:

See "Customizing the Identity System Pages" for an introduction to XSL stylesheets.

2.3.8.3 Images

HTML created by PresentationXML has embedded within it references to images. The Oracle Access Manager supplies its own set of GIF images and supports any type of image that can be read by a browser. Because the images are supplied by WebPass in direct response to requests from the browser, they are located in directories associated with Webpass, as described in "Directory Structure".

See also:

See "Image Library" for the naming convention for these files.

For details about incorporating custom images or styles after upgrading, see the Oracle Access Manager Upgrade Guide.

gifPathName and jsPathName Variables

Due to the change in location of all image files, a new gifPathName variable is defined in style.xsl. In addition to style.xsl, the following file also includes the gifPathName variable to mention the path for image locations:

install_dir\oblix\lang\langTag\msgctlg.js

For more information about msgctlg files, see "Modifying Catalog Files".

Note:

Stylesheets refer to the gifPathName variable to locate the image directory. JavaScript files refer to the jsPathName variable.

A language independent stylesheet picks up the images from the modified image path mentioned by the gifPathName variable, which is important for two reasons:

• It prevents hard-coding of URLs in the stylesheets and makes it easier to reuse the same stylesheet across styles.When customizing stylesheets, you should use this global variable whenever constructing a URL path to a GIF.

• It incorporates the current language and current style tag and generates the correct path.

Example: style.xsl with variables highlighted

The style.xsl wrapper resides in \style0 and can reside in your custom directory:

Identity_install_dir \identity\oblix\lang\en-us\style0\style.xsl

Identity_install_dir \identity\oblix\lang\en-us\Custom\style.xsl

A sample style.xsl is as follows.

<?xml version="1.0" encoding="ISO-8859-1"?> 
- <!--   Copyright (c) 1996-2005, Oracle All Rights Reserved.   --> 
- <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"      xmlns:oblix="http://www.oblix.com/">
  <xsl:variable name="styleName">style0/</xsl:variable> 
  <xsl:variable name="localeName">en-us</xsl:variable> 
- <xsl:variable name="gifPathName">
  ../../../lang/ 
  <xsl:value-of select="$localeName" /> 
  / 
  <xsl:value-of select="$styleName" /> 
  </xsl:variable>
  <xsl:variable name="jsPathName">../../../lang/shared</xsl:variable> 
- <xsl:variable name="cssPathName">
  ../../../lang/ 
  <xsl:value-of select="$localeName" /> 
  / 
  <xsl:value-of select="$styleName" /> 
  /coreid.css 
  </xsl:variable>
  <xsl:variable name="pageLayoutDir">LTR</xsl:variable>    </xsl:stylesheet>

2.4 PresentationXML Libraries

This section treats several of the components described earlier as parts of a library of information used to implement PresentationXML as if it were a programming language. It provides more detail and pinpoints the location of the files in directories.

2.4.1 Directory Structure

The Identity System can be installed starting at the root directory or in a specified subdirectory. For example:

Default on Windows: C:\Program Files\NetPoint\identity

Default on UNIX: /opt/netpoint/identity

In this manual: Identity_install_dir\identity

Prior to version 6.5, the PresentationXML library was provided under two directories and distributed depending upon how the files were likely to be used.

Version 6.5 and later versions include Language Packs that enable you to display static information to users in their native language. English is the default language for which no Language Pack is required. All Oracle Access Manager installations include a directory named with the en-us language tag (langTag).

When you install additional Language Packs you can see other langTag directories. For example, a French Language Pack results in a directory named fr-fr. For details about installing Language Packs, see theOracle Access Manager Installation Guide.

For version 6.5 and later, the default directory structure for PresentationXML Libraries is summarized as follows:

Identity_install_dir\identity\oblix\apps\AppName\bin Identity_install_dir\identity\oblix\apps\AppName\bin Identity_install_dir\identity\oblix\lang\langTag Identity_install_dir\identity\oblix\lang\langTag\style0 Identity_install_dir\identity\oblix\lang\shared WebPass_install_dir\identity\oblix\lang\langTag WebPass_install_dir\identity\oblix\lang\langTag\style0 WebPass_install_dir\identity\oblix\lang\shared WebPass_install_dir\identity\oblix\WebServices\XMLSchema

Figure 2-4 and Figure 2-5 show a default Identity Server Directory structure. Notice that the \en-us directory and the \shared directory reside at the same level in the \lang directory. Also notice that the Identity System application-specific directories reside under \apps (userservcenter, objservcenter, groupservcenter).

Figure 2-4 Sample Default Identity Server Directory Structure for Apps

Figure 2-5 Sample Default Identity Server Directory Structure for Lang

See also:

See "Directory Content" for more information.

2.4.2 Directory Content

The contents of default Identity System and WebPass directories are introduced here.

The contents of the default directories are outlined in Table 2-3. See the full list of applications, in the AppName column.

Table 2-3 Default PresentationXML Libraries

Default Identity System Directories	Contents
Identity_install_dir\identity\oblix\ apps\AppName\bin Where AppName can be common, groupservcenter, objservcenter, userservcenter, and so on.	Registration and parameter files specific to the application. Note: Dynamically-loadable code for applications is included in Identity Server executables.
Identity_install_dir\identity\oblix\ lang\langTag Where langTag represents an installed language, such as en-us (English) or fr-fr (French).	Message files for various applications.
Identity_install_dir\identity\oblix\ lang\langTag\style0	XSL stylesheets for applications point to templates in \shared Common images
Identity_install_dir\identity\oblix\ lang\shared	XSL stylesheet templates for various applications

The contents of the default WebPass directories identified earlier is outlined in Table 2-4.

Table 2-4 Default WebPass PresentationXML Libraries

Default WebPass Directories	Contents
WebPass_install_dir\identity\oblix\lang\langTag	Contains message files for various applications.
WebPass_install_dir\identity\oblix\lang\langTag\style0	Image files used in presenting the page. Copies of style0 stylesheets for client-side processing only.
WebPass_install_dir\identity\oblix\lang\shared	JavaScripts Copies of stylesheets for reference only.
WebPass_install_dir\identity\oblix\ WebServices\XMLSchema	Contains XML schema files for specific applications.

The differences between content of the Identity Server and WebPass PresentationXML directories are outlined in "Differences Between Identity Server and WebPass Directory Content".

Differences Between Identity Server and WebPass Directory Content

Summary of differences as follows:

• The XMLschema directory has no effect on PresentationXML operation and exists only on WebPass.

• JavaScripts and image files are always provided by WebPass Due to the change in location of all image files, a new gifPathName variable is defined in \identity\oblix\lang\langTag\style0\styles.xsl. A language independent stylesheet picks up images from the modified image path mentioned by the variable. Wrapper stylesheets include the styles.xsl stylesheet file. styles.xsl also contains the path for JavaScripts.

• Parameter, message, and registration files are used only by Identity applications, as part of the process that generates the OutPutXML.

• Stylesheets are available under both Identity Server and WebPass because they can be used in either:

  1. Server-side processing (the Identity Server builds the completed XSL stylesheet).

  2. Client-side processing (WebPass assists the client browser to build the final stylesheet by sending it pieces of other stylesheets to be included in-line).

For example:

Before v6.5: Identity_install_dir\identity\oblix\apps\AppName

Before v6.5: WebPass_install_dir\identity\oblix\apps\AppName

where AppName represents Group Manager (groupservcenter), Org. Manager (objservcenter), User Manager (userservcenter), and the like.

The AppName directory included include three significant subdirectories:

Before v6.5: AppName\bin

Before v6.5: AppName\ui

Before v6.5: AppName\xmlschema

Note:

Oracle Access Manager includes Language Packs that allow you to display static information to users in their native language. English is the default language for which no Language Pack is required. As a result, the directory structure and location of specific files has changed.

Following discussions provide more information on the content of the directories identified in the previous paragraphs.

Identity_install_dir\identity\oblix\apps\AppName\bin

The AppName directory refers to specific applications, including:

common

groupservcenter

objservcenter

userservcenter

and others

Each AppName \bin directory contains a registration file, as discussed in "Registration Files". In addition, each AppName \bin directory contains a small number of XML files that contain parameters for the specific application. All application-specific subdirectories include the same types of information. Although, the userservcenter\bin directory also includes several certificate files.

For example, in groupservcenter\bin, you can find the following files:

• groupservcenterreg.xml: The registration file for the Group Manager application.

• groupservcenterparams.xml: This file, and other files ending in params.xml, contain parameters that are used to guide execution of the application:

  • gsc_wf_params.xml: Create workflow, remove workflow, change attribute workflow parameters. The following files duplicate this information and are needed for special handling required for the IBM SecureWay directory server:

    gsc_wf_params-base.xml gsc_wf_params-sw.xml

    gsc_wfqs_params.xml: Create group basic template parameters.

• gscaclparams.xml: Example that shows a set of parameters and their value ranges for simple access control. Sample data is included that is not meant to be used in any deployment.

See also:

See "Oracle Access Manager Parameter Files" for a list of all parameter files whose content is designed to be changed by the user.

Note:

Do not change the content of any of these files unless the named file is listed in "Oracle Access Manager Parameter Files", the parameter is described there, and the description does not forbid you to change the parameter.

Note:

AppName.dll files, available before version 6.5, contained logic that the Identity Server executed for each application. Application module logic and libraries are now compiled in the Identity Server executable.

Identity_install_dir\identity\oblix\lang\langTag

To support multiple languages, Oracle Access Manager provides a specific named directory for each installed language. For example, \lang\en-us contains English language files; \lang\fr-fr contains French language files, and so on. Both the default style directory and any custom style directories you create are stored within each installed language directory.

Identity_install_dir\identity\oblix\lang\en-us\NewStyle
Identity_install_dir\identity\oblix\lang\en-us\style0

Identity_install_dir\identity\oblix\lang\fr-fr\NewStyle 
Identity_install_dir\identity\oblix\lang\fr-fr\style0 

Each langTag directory also contains message files for various applications in a specific language, such as English. A \help directory is also stored here.

You may customize messages in each langTag directory by editing specific msg.xml files.

See also:

See "Customizing Oracle Access Manager" for information on customizing a stylesheet.

Identity_install_dir\identity\oblix\lang\langTag\style0

The \style0 directory within each langTag directory provides default wrapper stylesheets that are specific to each application. For example:

gsc_ is the prefix for Group Manager wrapper stylesheets.

osc_ is the prefix for Org Manager wrapper stylesheets.

usc_ is the prefix for User Manager wrapper stylesheets.

wf_ is the prefix for workflow wrapper stylesheets.

There are others.

Each default wrapper stylesheet points to default global stylesheets in the \shared directory. In addition, several common image (GIF) files are stored here. When you add a style using the Configure Styles function in the Identity System Console, and copy from the Classic Style, the contents of \style0 are duplicated in your custom directory.

When customizing a style, you may overwrite a default wrapper stylesheet in your custom directory with a copy of the \shared stylesheet that you intend to customize. No wrapper stylesheet in your custom directory should inherit from (or reference) a default global stylesheet in the \shared folder.

The giflist.xml file included in previous versions is not available.

Note:

Oracle recommends that you retain the files in \style0 as they are in case you must revert to the default style. See "Customizing Oracle Access Manager" for more information.

Identity_install_dir\identity\oblix\lang\shared

The \shared directory contains default global stylesheets that apply to various applications in all languages.

You may edit stylesheets in \shared to institute a global change for all languages. However default stylesheets in \shared, and in \style0, are updated periodically by Oracle. A customized stylesheet in \shared or \style0 may be overwritten during product patches or upgrades. Other stylesheets may depend on the updates making it risky to overwrite an updated default stylesheet with the back up copy of a customized style. A better practice is to copy a default stylesheet from \shared into your custom directory, then customize the copy.

Note:

Oracle recommends that you retain the files in \shared as they are in case you must revert to the default style.

WebPass_install_dir\identity\oblix\lang\langTag

This directory contains message catalog files for various applications but is not an exact duplicate of the langTag directory on the Identity side:

• Copies of several message files

• Additional message files, such as webpassmsg.xml and others

• HTML files such as ldap_personoc.html

This directory also includes a help directory, and a docs directory for Web server related files. Again, you may edit message files here and propagate changes to other WebPass hosts.

See also:

See "Customizing Oracle Access Manager" for details.

WebPass_install_dir\identity\oblix\lang\langTag\style0

Contains copies of default XSL wrapper stylesheets for various applications from Identity_install_dir\identity\oblix\lang\langTag\style0.

Also included are the image files used when presenting the page, which are always provided by WebPass as direct responses to browser requests.

Note:

Oracle Access Manager relies on the images provided in this directory. Oracle recommends that you do not alter default images.

After you add a style to Oracle Access Manager and customize stylesheets, you must create the same style-related directory structure on the WebPass. You must copy all images you intend to use into your custom directory structure on WebPass. Even if you have made no changes to images you must still:

Copy Images From: WebPass_install_dir\identity\lang\en-us\style0

Copy Images To: WebPass_install_dir\identity\lang\en-us\CustomStyle

As with other default style files, images may be updated by Oracle periodically.

WebPass_install_dir\identity\oblix\lang\shared

This directory contains default global files that WebPass uses in response to requests:

• JavaScripts used by WebPass

• Copies of XSL stylesheets in Identity_install_dir\identity\oblix\lang\shared directory for use with client-side processing.

As with other default style files, these may be updated by Oracle periodically. Oracle recommends that you do not alter default files.You may copy and customize JavaScripts using the same methodology as if modifying a stylesheet on the Identity Server side.

See also:

See "Customizing Oracle Access Manager".

WebPass_install_dir\identity\oblix\WebServices\XMLSchema

This directory contains the XML schemas, as xsd files, that define elements specific to various applications. For example

gsc_... identifies Group Manager files.

osc_... identifies Org Manager files.

usc_... identifies User Manager files.

workflow... identifies Workflow files.

The XMLSchema has no affect on PresentationXML and is included only on WebPass.

As with other default style files, these may be updated by Oracle periodically.

The Oracle Access Manager system relies on these files. Oracle recommends that you retain the files in this directory as is.

2.4.3 Stylesheets

As discussed in the previous sections, the default XSL stylesheets and wrapper stylesheets for various Identity System applications can be found in the following directories:

Identity_install_dir\identity\oblix\lang\langTag\style0 -- wrapper stylesheets
Identity_install_dir\identity\oblix\lang\shared -- stylesheets

WebPass_install_dir\identity\oblix\lang\langTag\style0 
WebPass_install_dir\identity\oblix\lang\shared 

On WebPass, copies are included for client-side processing if that method is used.

The following base stylesheet files provide a foundation for all other stylesheets and contain relative pointers to other stylesheets:

• basic.xsl: Provides templates to define attributes and status, and to control display information, including references to the font.xsl and title.xsl files.

  For more information, see "basic.xsl".

• font.xsl: Contains templates to define HTML size, fonts and colors for recurring text such as page headings.

  For more information, see "font.xsl".

• title.xsl: Contains the default titles for the HTML pages.

  For more information, see "title.xsl".

• navbar.xsl: Provides the template to define the Navigation Bar.

  For more information, see "navbar.xsl".

• searchform.xsl: Provides templates to create the Searchform line. The following searchform.xsl files appear as well, and all point to searchform.xsl:

  gsc_searchform.xsl

  osc_searchform.xsl

  usc_searchform.xsl

  For more information, see "searchform.xsl".

Important:

Oracle periodically updates stylesheets and recommends retaining default stylesheets to serve as a predictable stylesheet library.

2.4.3.1 basic.xsl

The basic.xsl wrapper stylesheet in the \lang\en-us\style0 (or your custom style directory) provides references to style.xsl, msgctlg.xsl, and to the basic.xsl stylesheet located in the \shared subdirectory.

The global, language-neutral basic.xsl file in the following directories includes the variables in Table 2-5 and the templates in Table 2-6:

Identity_install_dir\identity\oblix\lang\shared
  WebPass_install_dir\identity\oblix\lang\shared

Table 2-5 Variables Defined in \shared\basic.xsl

Name	Description
textSLength	The default length for a textbox.
textSMaxLength	The maximum length for a textbox.
namePrefix	Oblix internal, do not change.
singlequote	Defines a constant for the single quote character. This is specified as a character that needs to be handled in a special manner and is required for literal strings in JavaScript code enclosed in single quotes.
charsToEscape	Used in the PrepForJS XSL template. This is a list of characters that must be escaped with &.

Table 2-6 identifies actual templates available in basic.xsl.

Table 2-6 \shared\basic.xsl Templates

Name	Description
oblix: ObDisplay	Each display type (for example checkbox, textbox, bitstring, and so on) is nested within the oblix:ObDisplay element. This matching template, sometimes called the Dispatcher, calls the corresponding display type template to properly generate the HTML for that display type. Additional HTML logic is added to properly include the + or - button in modify mode.
oblix:ObBitString	Generates the bitstring display type data as HTML text in view mode or as an HTML textbox in modify mode.
oblix:ObBoolean	Generates the Boolean display type data as text strings in view mode or radio buttons in modify mode.
oblix:ObCheckBox	Generates the checkbox display type data as text strings in view mode or an HTML checkbox in modify mode.
oblix:ObDate	In view mode this template generates the date display type as text strings, using a format corresponding to the date type specified (ObMonthDYDate, ObDMYDate, for example). In modify mode this template generates the date display type as an HTML select box (one for year, one for month, and one for day). This template calls the ObDateValue template to generate the actual select boxes.
oblix:ObDateValue	In view mode this template generates one entered value of the date display type data as a text string with a format corresponding to the date type specified (for example ObMonthDYDate, ObDMYDate). In modify mode it generates an HTML select box (one for year, one for month, and one for day).
oblix:ObDn	In both view and modify mode, generates the dn display type as hyperlink text. The dn value is also prepended with an image, if one is supplied from the XML.
oblix:ObEmail	In view mode generates the email display type as hyperlinked text in the form mailto:<email address>). In modify mode, this is an HTML text box.
oblix:ObFacsimile TelNum	In view mode, this template generates the facsimileTelNum display type data as a text string with the fax value first, followed by optional parameters describing whether it is TwoDimensional, FineResolution, b4Length, a3Width, b4Width, uncompressed, and unlimitedLength. In modify mode, the text string is displayed as an HTML textbox and the parameter properties are displayed as checkboxes.
oblix:ObGeneric Selector	Generates the generic selector display type data as hyperlinked text in both view and modify mode. If the data is for a user, a user image is prefixed. If the data is for a group, a group image is prefixed. If the data is an object, an object image is prefixed. In addition, the modify mode also generates the selector button.
oblix:ObGif	Generates the GIF display type data as an image using the src, width, height, and alt information from the XML, in both view and modify mode. In modify mode, a file upload box is also generated.
oblix:ObGifUrlText	A named template that is called by ObGifUrl. Used only in modify mode to generate the gifurl information as a textbox with the specified length and maxlength.
oblix:ObGifUrl	In both view and modify mode, generates the gifurl display type data as an image using ObImage's XML attributes obhref (the hyperlink), obalt (the alternate text), obwidth (the width of the image), and obheight (the height of the image). In modify mode, an additional text box is generated by calling the template ObGifUrlText.
oblix:ObLocationDn	Generates the location dn display type data as a link by calling the ObLink template.
oblix:ObMedia	Generates the media display type data as a hyperlink with an image, if one is supplied or the specified display name, if one is supplied. For modify mode, an additional file browse button is also generated.
oblix:ObPassword	In modify mode, generates an HTML password input box with the specified length and max length. If oboldpswd is true, then the old password is also prompted for, using a password input box. (This element is not used in view mode).
oblix:ObPostalAddress	In view mode, generates the postal address display type value as a text string. In modify mode, the values are presented as modifiable data in text boxes.
oblix:ObQueryBuilder	In modify mode, each value is displayed as modifiable data in a textbox. A querybuilder button is also generated. (This element is not used in view mode).
oblix:ObRadio	In view mode, generates the radio display type values as text strings. In modify mode, the values are generated as HTML radio buttons.
oblix:ObSelect	In view mode, generates the select display type values as text strings. In modify mode, the values are generated as HTML select boxes.
oblix:ObSMIMECertificate	Generates the SMIMECertficate display type as text strings.
oblix:ObTextM	In view mode generates the textM display type value as a text string. In modify mode the values are generated as HTML multi-line text boxes with the specified columns and rows.
oblix:ObTextS	In view mode, generates the textS display type value as a text string. In modify mode, the values are generated as HTML single-line text boxes with a specified maxlength and length.
oblix:ObNumericStr	In view mode, generates the numeric string display type value as a text string. In modify mode, the value is generated in a text box with the specified maxlength and length, along with a JavaScript validation to ensure that the text field only accepts numeric values.
oblix:ObValue	Generates the PC Data text in the Oblix:ObValue element.
oblix:ObApplet	Generates an HTML applet. Information includes name, codebase, code, width, height, align, target, and archive. If the applet requires input parameters, they are specified in the oblix:ObParam element.
oblix:ObScripts	Calls the oblix:ObScript template for each ObScript element within the ObScripts element.
oblix:ObScript	Generates the script tag to allow the JavaScript specified in the Oblix:ObScript element to be referenced within the HTML.
oblix:ObButton	Generates a button, either a hyperlink text or image, using the information provided in the XML. Information includes the href, mouse over, and optional image. If an image is not specified the anchor text is displayed.
oblix:ObInput	Generates the HTML input tag using the specified information in the XML element.
oblix:ObLink	In view mode generates a hyperlink with the specified href and mouse over values, along with either an image or a text string. In modify mode a text box is generated.
oblix:ObImage	Generates an image using the specified obwidth, obheight, obalt, and href values.
requestLessValue	A called template that generates the proper HTML tag to enable the "request a ticket to remove an attribute" functionality.
requestMoreValue	A called template that generates the proper HTML tag to enable the "request a ticket to modify an attribute" functionality.
outputDateChoices	A called template that generates the date choices for modify mode.
ObDateMonth	A called template that generates the month select box in modify mode.
ObDateDay	A called template that generates the day select box in modify mode.
ObDateYear	A called template that generates the year select box (by default, 1993 - 2012) in modify mode.
ObDateHourOption	A called template that generates the hour select box (00 - 23) in modify mode.
ObDateTZHourOption	A called template that generates the hour select box (00 - 12) in modify mode.
ObDateMinOrSecOption	A called template that generates the minute or the hour select box (00 - 59) in modify mode.
requiredAttrInput	A called template that generates hidden HTML input tags, intended for internal purposes. This is called by the Oblix:ObDisplay template.
moreValue	A called template that generates the proper HTML tag to enable the "add more values" functionality (The + button).
lessValue	A called template that generates the proper HTML tag to enable the "remove a value" functionality (The - button).
oblix:ObDisplayProperties	A called template that adds the onX event which can be any of: onChange, onClick, onDblClick, onDragStart, onFilterChange, onHelp, onKeyDown, onKeyPress, onMouseDown, onMouseMove, onMouseOut, onMouseOver, onMouseUp, onSelectStart, or disabled.
oblix:ObError	Generates the error message.
oblix:ObTextMessage	Generates the specified text message.
MakeHiddenObAttribute	A called template that generates hidden HTML input tags, intended for internal purposes.
ObDisplayPrettyPrint	A called template that generates values in a table format.
ObLinkPrettyPrint	A called template that generates link values in a table format.
ObLinkModifyPrettyPrint	A called template that generates each link values as a checkbox in a table format.
Makeobvarname	A called template that converts the input parameter from x to Obx, changing hyphens to underscores.
AddLineBreaks	A called template that adds line breaks to a string, in the places where the string contains &#xA;
oblix:PrepForJS	A called template that escapes characters in preparation for calling a JavaScript.
oblix:AddJavaPluginLayer	A called template that generates an error display if the Java Runtime Environment 1.3 or higher is needed but not available.

2.4.3.2 font.xsl

This stylesheet contains templates to define HTML size, fonts and colors for recurring text such as page headings. The font.xsl file in the following directories includes the variables in Table 2-7 and templates in Table 2-8.

 Identity_install_dir\identity\oblix\lang\shared
  WebPass_install_dir\identity\oblix\lang\shared

Table 2-7 Variables Defined in font.xsl

Name	Description
pageHeaderSize	Defines the size of the heading for the page.
pageHeaderColor	Defines the color of the heading for the page.
pageHeaderFont	Defines the font of the heading for the page.
subHeadingSize	Defines the size of the subheading for the page.
subHeadingColor	Defines the color of the subheading for the page.
subHeadingFont	Defines the font of the subheading for the page.
contentTitleSize	Defines the size of the content title (for example the attribute display name in a profile page).
contentTitleColor	Defines the color of the content title.
contentTitleFont	Defines the font of the content title.
contentTextSize	Defines the size of the content text (for example the attribute value in a profile page).
contentTextColor	Defines the color of the content text.
contentTextFont	Defines the font to be used for the content text.
pageWarningSize	Defines the size of the warning message.
pageWarningColor	Defines the color of the warning message.
pageWarningFont	Defines the font to be used for the warning message.
anchorTextSize	Defines the size of the anchor text to be used with login.xsl and logout.xsl.
anchorTextColor	Defines the color of the anchor text for login.xsl and logout.xsl.
anchorTextFont	Defines the font of the anchor text for login.xsl and logout.xsl.

Table 2-8 identifies the templates in font.xsl.

Table 2-8 Templates Defined in font.xsl

Name	Description
addPageHeaderAttr	A called template that is used to set the proper color, size, and font for the page header. (for example the word Profile, which is the title of a profile page).
addSubHeadingAttr	A called template that is used to set the proper color, size, and font for the sub heading. (for example the Panel name in a profile page).
addContentTitleAttr	A called template that is used to set the proper color, size, and font for the content title. (for example the attribute display name in a profile page).
addContentTextAttr	A called template that is used to set the proper color, size, and font for the content text. (for example the attribute value in a profile page).
addPageWarningAttr	A called template that is used to set the proper color, size, and font for the page warning.
addAnchorTextAttr	A called template that is used to set the proper color, size, and font for the anchor text created by login.xsl and logout.xsl.

2.4.3.3 title.xsl

This stylesheet the default titles for the HTML pages. The title.xsl file in the following directories include the variables in Table 2-9. There are no templates in title.xsl.

Identity_install_dir\identity\oblix\lang\shared
 WebPass_install_dir\identity\oblix\lang\shared

Table 2-9 Variables Defined in title.xsl

Name	Description
corpdirTitle	HTML title for all Publisher pages.
userservcenterTitle	HTML title for all User Manager pages.
groupservcenterTitle	HTML title for all Group Manager pages.
objservcenterTitle	HTML title for all Organization Manager pages.
querybuilderTitle	HTML title for all Query Builder pages.
selectorTitle	HTML title for all Selector pages.
lpmTitle	HTML title for all Lost Password Management pages.
defaultTitle	HTML title for all common pages shared across all applications.
corpdir	For internal use only; used to determine the context of the current page.
userservcenter	Internal use only; used to determine the context of the current page.
groupservcenter	Internal use only; used to determine the context of the current page.
objservcenter	Internal use only; used to determine the context of the current page.

2.4.3.4 navbar.xsl

In the \shared subdirectory, navbar.xsl provides the template to define the Navigation Bar. The following files in the \shared subdirectory also point to navbar.xsl: gsc_navbar.xsl, osc_navbarm.xsl, usc_navbar.xsl.

The navbar.xsl file in the following directories include the templates in Table 2-10. There are no variables in navbar.xsl.

Identity_install_dir\identity\oblix\lang\shared
  WebPass_install_dir\identity\oblix\lang\shared

Table 2-10 Templates Defined in Navbar.xsl

Name	Description
oblix:ObNavbar	Generates the Navigation Bar (Navbar) that appears at the top of every Identity System page. The navbar is made up of several significant parts: Logged in user identification, a list of selectable applications (User Manager, Organization Manager, and so on), Help/About/Logout buttons, application functionality (for example My Identity, Reports, and so on), and Tabs (if there are multiple tabs).
oblix:ObApps	Generates the list of selectable applications.
localButton	A called template that generates a button by filling in the HTML information about the href, mouseover, mouseout, and image or anchor text.
oblix:ObApplication/ oblix:ObTabs/oblix:ObButtons	Generates the buttons used for selecting different tabs.
oblix:ObApplication/ oblix:ObFunctions/oblix:ObButton	Generates the buttons used for selecting the different functionalities within the application (for example My Identity).
oblix:ObApplication/ oblix:ObTitle/oblix:ObButton	For internal use only, used to set the current context.

2.4.3.5 searchform.xsl

This template was previously distributed but now templates to create the Searchform line are located in searchform.xsl. The following searchform.xsl files appear as well, and all point to searchform.xsl:

gsc_searchform.xsl
   osc_searchform.xsl
   usc_searchform.xsl

The searchform.xsl file in the following directories include the templates in Table 2-11. There are no variables in searchform.xsl.

Identity_install_dir\identity\oblix\lang\shared 
WebPass_install_dir\identity\oblix\lang\shared

Table 2-11 Templates Defined in searchform.xsl

Name	Description
oblix:ObSearchForm	Generates the Searchform, which is located directly beneath the Navigation Bar on most pages. The Searchform may contain many SearchRows.
oblix:ObSearchForm/ oblix:ObSearchRow	Generates one row of the search functionality. A row consists of 2 select boxes and one text box, usually one for each search request, such as a search for "full name" "that contains" "John".
oblix:ObSearchForm/ oblix:ObAdvanced Search	Generates the search more, search less, and search all buttons if the advanced search capability is enabled.

2.4.4 XML Schema Elements Library

As mentioned earlier, the OutPutXML information generated by each program within each Identity System application is hard-coded and is not directly changeable by users. The content of the OutPutXML is not controlled by the content of the XML schema file. The file is provided only as a developer's aid, to help you design XSL stylesheets to work with the OutPutXML. Oracle recommends that you not change any of the XML schema files.

The following is presented for information only. The XMLSchema directory in WebPass_install_dir\identity\oblix\WebServices contains several schema files specific to each application. For example:

gsc_administrationMain.xsd ...
osc_administrationMain.xsd ...
usc_administrationMain.xsd ...
and others ...

If you look at these files, you see that some contain element definitions that exist only within that file, and many contain references to other schema files.

If you trace nested references deeply enough, you come to the following six files, which are provided under the XMLSchema directory for the common application:

• navbar.xsd: Defines the content for the Navigation Bar, the top two lines of each page, including the application name, help and logout buttons, and the various tabs to select other modules within the application.

• searchform.xsd: Defines the SearchForm line, the line available on some pages, that starts with the graphic labeled search. It may include additional lines for more complex search combinations.

• component_panel.xsd: Defines the content for profiles, the sets of descriptive information for users, groups or organizations.

• component_basic.xsd: Defines many of the lowest level elements, and includes displaytype.xsd and error.xsd.

• displaytype.xsd: Defines formatting for each of the Oracle Access Manager display types.

• error.xsd: Defines the ObError element.

The rest of this section describes the elements that are defined within each of these files.

Note:

It is strongly recommended that you leave the content of these files untouched, to serve as a predictable template library.

2.4.4.1 displaytype.xsd

The displaytype.xsd file in WebPass_install_dir\identity\oblix\WebServices\XMLSchema contains the elements described in Table 2-12. All elements in this file are in the Oblix namespace.

Table 2-12 displaytype.xsd Schemas

Name	Description
ObDisplay	An element that contains information about a value (or set of values) being generated. This element usually maps to one of the display types such as email or date. This element may contain two children: the element ObDisplayProperties, which is optional, and a required element whose name maps to the display type (for example, ObCheckBox or ObDate). This element contains the following required attributes: obname: The name, usually the attribute name, for the value being generated. obdisplayName: The display name/user friendly name/printed name. obdisplayType: The display type for this value. obsemanticType: The semantic type for this value). obmode: One of the list: view, modify, or plain. obshowLabel: True or false, indicating whether to show the display name when outputting this value. obrequired: True or false, indicating whether this is a required value, meaning there must be at least one value entered by the user in modify mode). obcardinality: SingleValued or multiValued, indicating whether this is a single-valued or multi-valued attribute. obcanRequest: True or false, indicating whether the user can change this value in modify mode.
ObDisplay Properties	Contains zero or more ObDisplayProperty elements.
ObDisplayProperty	Contains the necessary display property for an onX event, which can be onChange, onClick, onDblClick, onDragStart, onFilterChange, onHelp, onKeyDown, onKeyPress, onMouseDown, onMouseMove, onMouseOut, onMouseOver, onMouseUp, onSelectStart, or disabled. The XML attribute obname contains the onX event name and the XML attribute obvalue contains the value for the onX event.
ObBitString	Describes the BitString display type. Contains zero or more ObValue elements, each corresponding to a value. In addition, there are two optional XML attributes: oblength, for the length of the textbox and obmaxLength for the maximum length of the textbox.
ObBoolean	Describes the Boolean display type. Contains a required XML attribute obvalue which contains the value true or false.
ObButton	Describes a button. A button contains six optional XML attributes: obaction: The action. obmouseover: The mouse over message. obhref: The href. obimageUrl: The location of the image for the button. obanchorText: The alternate text if there is no image. target: Provided for future use and currently not used.
ObCheckBox	Describes the checkbox display type. Contains zero or more ObChoice elements.
ObChoice	Describes a choice. Usually nested within a display type that permits a choice, such as ObCheckBox. Contains an optional XML attribute obselected. Possible values for obselected are true or false. The default value when this attribute is not specified is false. If a value is selected, it means that the value is one that has been chosen by the user. If a value is not selected, that means it is a possible choice but not one actually chosen by the user. In addition the ObChoice element contains a required XML attribute obdisplayName corresponding to the display name (the user friendly name) for this choice.
ObDate	Describes the date display type. Contains zero or more ObDateValue elements. In addition, it contains the following optional attributes: obseparator, the string separating the parts of the date. If this is not specified, the default value is /. obformat: The format in which the date is to be presented. If not specified, the default value is USStandard. Possible values include USStandardFull, EUSStandard, EUSStandardFull, and USStandard. obdateType: The manner in which the date is carried as data. Possible values include ObIntegerDate, ObMDYDate, ObDMYDate, ObDMonthYDate, ObISO8601Date, and ObUnknownDate).
ObDateValue	Describes a date value. Contains the following required XML attributes: obmonth: A text string that represents the month. obday: A text string that represents the day. obyear: A text string that represents the year. In addition an optional XML attribute obbadDate describes whether the given date is malformed. The default value for the obbadDate attribute is false meaning the date is not malformed. Possible values are true and false.
ObDn	Describes the dn display type. Contains zero or more obLink elements.
ObEmail	Describes the email display type. Contains zero or more ObValue elements. In addition, the ObEmail element may contain two optional XML attributes: oblength: The actual length of the textbox. obmaxLength: The maximum allowed length of the textbox.
ObFacsimileTelNum	Describes the facsimile telephone number display type. Contains zero or more ObValue elements and zero or more ObFaxParam elements.
ObFaxParam	Contains an XML attribute obdisplayName.
ObForm	Contains information for generating a form. Contains zero or more ObInput elements. In addition, it contains: obname: The required XML attribute providing the name of the form. obaction: An optional XML attribute providing the action to take when the form is submitted. obenctype: An optional XML attribute providing the encryption type for the form. obmethod: An optional XML attribute specifying the method, either post or get, for this form. The default method is post.
ObGenericSelector	Describes the generic selector display type. Contains zero or more ObLink elements and at most one optional ObButton element.
ObGif	Describes the GIF display type. Contains zero or more ObImage elements.
ObGifUrl	Describes the gifurl display type. Contains zero or more ObImage elements. In addition it contains two optional XML attributes: oblength: The length of the textbox obmaxLength: The maximum length of the textbox.
ObLocationDn	Describes the location dn display type. Contains zero or more ObLink elements.
ObMedia	Describes the media display type. Contains zero or more ObLink elements.
ObMime	Describes the mime display type. Contains a required XML attribute obtype, and an optional XML attribute obfileExt (used to define file extensions).
ObPassword	Contains zero or more ObValue elements. Additionally, it may contain three optional XML attributes: oblength: The length of the textbox. obmaxLength: The maximum length of the textbox. oboldpsw: Which indicates whether to display information about the old password. Possible values for the oboldpsw attribute are true and false.
ObPostalAddress	Contains zero or more ObPostalValue elements. Contains two optional XML attributes: oblength: The length of the textbox. obmaxLength: The maximum length of the textbox.
ObPostalSubString	PC Data containing the postal sub string.
ObPostalValue	Contains zero or more ObPostalSubString elements.
ObSelect	Describes the select display type. Contains zero or more ObChoice elements. In addition, it contains two optional XML attributes: obmultiple: True or false; the default value is false. obsize: The size of the select box.
ObTextM	Describes the textM display type. Contains zero or more ObValue elements. In addition, it may contain three optional attributes: obrows: The number of rows for the multi-line textbox. obwrap: Indicates whether the text should wrap, and takes the values true and false. obcols: The number of columns for the multi-line textbox).
ObTextMessage	PC Data describing a text message. Usage for this element is context dependent. One frequent use is to output an error message.
ObTextS	Describes the textS display type. Contains zero or more ObValue elements and zero or more ObTextMessage elements. In addition, it may contain two optional attributes: oblength: The length of the textbox. obmaxLength: The maximum length of the textbox.
ObQueryBuilder	Describes the query builder display type. Contains zero or more ObValue elements and an optional ObButton element. In addition, it may contain two optional attributes: oblength: The length of the textbox. obmaxLength: The maximum length of the textbox.
ObRadio	Describes the radio display type. Contains zero or more ObChoice elements.
ObSMIMECertificate	Contains zero or more ObSMIMEValue elements. In addition, it contains three optional ObButton elements.
ObSMIMEValue	Contains zero or more ObNameValuePair elements and two optional ObButton elements.
ObNameValuePair	Contains two required XML attributes: obcertinfo: Which has three possible values: issuer, validfrom, and validto. obcertvalue: Which is the value that is described by this ObNameValuePair.
ObScript	Contains information for including a script. The name of the script is described by the required XML attribute obname.
ObScripts	Contains one or more ObScript elements.
ObValue	PC Data containing a value.
ObImage	Contains one required XML attribute: obhref: The href Also contains three optional XML attributes: obalt: The alt text. obwidth: The width of the image. obheight: The height of the image.
ObInput	Contains the information required to generate an HTML input tag. Contains up to three XML attributes: obtype: The type of input (required). obname: The name of the input (required). obvalue: The value of the input (optional).
ObLink	Contains zero or more ObImage elements and zero or more ObMime elements. In addition, it contains up to three XML attributes: obhref: The href (required). obmouseOver: The mouse over message for the link (optional). obdisplayName: The display name for the hyperlink (optional).
ObNumericStr	Contains zero or more ObValue elements. In addition, it may contain two optional XML attributes: oblength: The length of the textbox. obmaxLength: The maximum length of the textbox.
ObApplet	Contains information describing an applet. Contains zero or more ObParam elements, each describing a parameter for the applet. In addition, it contains the one optional XML attribute obarchive and the required XML attributes obname, obtarget, obcodeBase, obcode, obwidth, obheight, and obalign, all of which map to information required in the HTML applet tag.
ObParam	Contains the name and value for a parameter, in the form of two required attributes: obname and obvalue.

2.4.4.2 component_basic.xsd

The component_basic.xsd file in WebPass_install_dir\identity\oblix\WebServices\XMLSchema contains the elements described in Table 2-13. All elements in this file are in the oblix namespace.

Table 2-13 component_basic.xsd Schemas

Name	Description
ObRequestInfo	Internal use only.
ObStatus	Contains the returned status value, either 0 or 1, for the request.
ObVariableText	Contains one ObDisplay element.
ObAttribute	Contains zero or more ObDisplay elements and an optional ObTextMessage element. In addition, an optional XML attribute obattrName may be used to specify the attribute name.

2.4.4.3 navbar.xsd

The navbar.xsd file in WebPass_install_dir\identity\oblix\WebServices\XMLSchema contains the elements described in Table 2-14. All elements in this file are in the oblix namespace.

Table 2-14 navbar.xsd Schemas

Name	Description
ObTabs	Consists of zero or more buttons used for describing the different tabs configured for the current application.
ObNavbar	Describes the navigation bar. It may contain up to 8 optional elements: ObRequestInfo, ObScripts, ObMisc, ObApps, ObForm, ObApplication, ObFunctionsButton, and ObStatus. In addition, a required XML attribute obbgcolor specifies the color of the background for this page.
ObMisc	Describes the buttons that are used for help, about, and logout.
ObApps	Contains zero or more ObApplication elements. Each ObApps element describes an application, such as User Manager or Organization Manager.
ObApplication	Describes the details of a specific application, usually nested within ObApps. Contains any of the following four elements: ObButtons: Specifies the URL/button information to get to that application. This information is only filled in if the user is not in that application. ObFunctions: Specifies the functions available for this page. ObTabs: Specifies the tabs to be used on this page, if any. ObTitle: Specifies the title image for this application.
ObFunctions	Describes the functions available on the current page. Consists of: ObButtons: For example, non-workflow and administrative functionality such as configure proxy, deactivate user or create user. There are zero or more of these. ObWorkflowFunctions: For example, workflow incoming request, workflow outgoing request or workflow ticket search form. ObAdminFunctions: Administrative functions, such as delegated administration or workflow definition.
ObAdminFunctions	Describes the administrative functionality such as workflow definition and delegated administration.
ObWorkflow Functions	Describe the workflow functionality such as workflow incoming request, workflow outgoing request or workflow ticket search form.
ObTitle	Consists of zero or more buttons that describe the image that applies to the current application.
ObApplicationFunc	Provides further context defining where the user is in screen navigation. This element is not used unless the user is past first level navigation. An example is the navigation information that is contained here after the user clicks on "Configuration"

2.4.4.4 searchform.xsd

The searchform.xsd file in WebPass_install_dir\identity\oblix\WebServices\XMLSchema contains the elements described in Table 2-15. All elements in this file are in the oblix namespace.

Table 2-15 searchform.xsd schemas

Name	Description
ObSearchForm	Describes a search form which consists of zero or more of the following elements: ObHelpContext, ObRequestInfo, ObScripts, ObForm, ObDisplay, ObButton, ObAdvancedSearch, ObSearchRow, and ObStatus.
ObSearchRow	Describes each row of the search form, consisting of zero or more ObDisplay elements. The SearchRow contains the information required to output a table row which contains 3 fields: a text box, and two select boxes.
ObAdvancedSearch	Indicates if the advanced search capability is enabled through inclusion of and the value set for the optional XML attribute obadvancedSearchOn.
ObHelpContext	PC Data containing information about the context of the page, used for online help.

2.4.4.5 component_panel.xsd

The searchform.xsd file in WebPass_install_dir\identity\oblix\WebServices\XMLSchema contains the elements described in Table 2-16. All elements in this file are in the oblix namespace.

Table 2-16 component_panel.xsd schemas

Name	Description
ObHeaderPanel	Describes the header panel, which contains a number of LDAP attributes described by zero or more ObAttribute elements. In addition, a panel is described with a number of optional XML attributes, those specified by the administrator during panel configuration in the Identity System Console. A profile page can have a number of panels but only one header panel.
ObPanel	Describes a panel, which contains a number of LDAP attributes described by zero or more ObAttribute elements. In addition, a panel is described with a number of optional XML attributes, those specified by the administrator during panel configuration in the Identity System Console. A profile page can have a number of panels but only one header panel.

2.4.4.6 error.xsd

The searchform.xsd file in WebPass_install_dir\identity\oblix\WebServices\XMLSchema contains the elements described in Table 2-17. All elements in this file are in the oblix namespace.

Table 2-17 error.xsd schemas

Name	Description
ObError	Describes an error, including an error message contained in the ObTextMessage element.

2.4.5 Image Library

Oracle Access Manager provides default GIF files used in presenting the page and supports any type of image the browser supports. These are always provided by WebPass as direct responses to browser requests and are located in WebPass_install_dir\identity\oblix\lang\langTag\style0, as described in "Directory Structure".

Important:

Oracle Access Manager relies on these images files and Oracle recommends that you copy the files to your custom directory, make changes, then include the updated copies in stylesheets. See "Customizing Oracle Access Manager". On rare occasions, if your custom image does not appear but the default does, you may need to change the default image.

Most of the filenames conform to a standard naming convention. Understanding this convention helps you avoid referencing the wrong image in your stylesheets. An image name includes three elements: <ImagePrefix><DescriptiveName><ImageState>. For example:

2FTABgeneratereport2.gif

ImagePrefix: In the previous example, 2FTAB is the ImagePrefix. This part of the GIF image name describes the way in which the image is used. See the following table for a list and description of the various values for the ImagePrefix.

DescriptiveName: In the example, generatereport is the DescriptiveName. This part of the GIF image name is an attempt to provide a user friendly description of the function, tab, content, or navigation feature with which the image is associated.

ImageState: This part of the GIF image name indicates whether the image shows as active or inactive. Active means that the function, tab, content or navigation feature matches what is currently displayed on the page. Inactive means that it does not; the image represents an alternative that could be selected. The images are usually identical, except that the active image is in a darker color. The difference in naming is:

• Active Images: ImageState is set to 2 to represent active images.

• Inactive Images: ImageState is omitted for inactive images.

The following is an image for 2FTABgeneratereport2.gif. This is the active image.

The following is an image for 2FTABgeneratereport.gif, the inactive image, shown for comparison.

Table 2-18 lists the possible ImagePrefix values for image files:

Table 2-18 ImagePrefix Types

Image Type	ImagePrefix Value	Description
Content Buttons	CBUTTON	Associated with activities that select certain subsets of the available data, such as selecting a certain user or adding data.
Content Buttons (Small)	2CBUTTON	Smaller versions of the same.
Content Image	CIMAGE	Descriptive images, not associated with a choice.
Content Tabs	CTAB	Used to select major categories of data, such as a group type.
Content Tabs (Small)	2CTAB	Smaller versions of the same.
Function Tab	FTAB	Associated with activities that the user wants the Identity System to perform, such as creating a group, or generating a report.
Function Tabs (Small)	2FTAB	Smaller versions of the same.
Login Screen Images	LOGIN	These are not for customer use.
Page Navigation	NAV	Used to indicate a change to a different screen, usually with no modification to data.
Page Navigation (Small)	2NAV	Smaller versions of the same.

2.4.6 JavaScript Library

Most JavaScript files are located as described in "Directory Structure", in WebPass_install_dir\identity\oblix\lang\shared.

JavaScript files refer to the jsPathName variable to locate the image directory. For details, see "gifPathName and jsPathName Variables".

Language-specific messages are referred to through variables in message catalog files. See "Changing Message Catalogs and MouseOver Text" a for details.

There are too many JavaScript files to document the content of all of them here. However, this section provides a list of functions and what they do, for some of the most frequently used Javascript files. You may find a function in this Library that you want to use at a non-standard place in the stylesheet, or the function might serve as a starting point for a new one of your own.

Note:

Again, Oracle recommends that you retain files in \shared as a reliable default. You may, however, copy the files in \shared to a custom directory, change the content in the copy, then write your stylesheets to include the new JavaScript files and functions. See "Customizing Oracle Access Manager".

2.4.6.1 Confirm.js

Located in WebPass_install_dir\identity\oblix\lang\shared, confirm.js includes the functions described in Table 2-19.

Table 2-19 Confirm.js

Function Name	Description
myConfirm	Takes a message and a URL as arguments. A confirmation window appears with the message. If the user presses okay the browser takes the user to the URL.
confirmDelete	Confirmation of a delete action in the form of a confirmation window appears. If the user presses okay the browser takes the user to another Web page whose href uses most of the href of the original URL, but replaces the program information with the argument URL.
confirmClear	Outputs a Windows confirmation box asking if the user wants to clear x where x is the argument name. If so, the browser takes the user to a new URL based on the information provided in the argument URL.

2.4.6.2 Customizeresults.js

Located in WebPass_install_dir\identity\oblix\lang\shared, Customizeresults.js includes the functions described in Table 2-20.

Table 2-20 Customizeresults.js

Function Name	Description
configureCustomizeresults FormAndSubmit	Takes no arguments; validates the browse results columns selected before submitting the form. Validation restrictions include requiring at least one attribute to be selected, no attribute shall be selected twice, and selected attributes must not be separated by blank selections.
cancelCustomizeresults FormAndSubmit	Resets the customizeResultsForm such that no validation is performed.

2.4.6.3 Deactivateuser.js

Located in WebPass_install_dir\identity\oblix\lang\shared, Deactivateuser.js includes the functions described in Table 2-21.

Table 2-21 Deactivateuser.js

Function Name	Description
startSearchAndSubmit	Submit the monitor search form.
DeactContinueSearch	Provides the logic for pressing previous/next in the deactivate search results page. The argument subprogram signals whether this is for previous or next. For next, if this is already the last set of search results, an error message pops up saying so. For previous, if this is the first page, an error message indicatse this.
submitresults	Submit the deactivate search form with validation. If validation succeeds the function submits the argument URL to the Identity Server.
toggleselect	Toggle the search results form checkboxes from false to true.
sortDeactivatedUsers (sortBy, sortOrder)	Set the sort information in the deactivate search results page using the argument information.

2.4.6.4 Groupsubscription.js

Located in WebPass_install_dir\identity\oblix\lang\shared, Groupsubscription.js includes the functions described in Table 2-22.

Table 2-22 Groupsubscription.js

Function Name	Description
resetsubscription	Reset the ObGroupsToSubscribeForm form.
submitresults(URL)	Submit the ObGroupsToSubscribeForm form after formulating the required information for the Identity Server.

2.4.6.5 Helpcommon.js

Located in WebPass_install_dir\identity\oblix\lang\shared, Helpcommon.js includes the functions described in Table 2-23.

Table 2-23 Helpcommon.js

Function Name	Description
ObHelp	Build the help URL by appending to the argument helpUrl using the current page's help context.
SetHelpContext	Set the help context of the current page using the information provided from the arguments.
BuildParameter	Helper function used by ObHelp to build the name value pair parameters into the form &name=value.

2.4.6.6 Horizontalprofile.js

Located in WebPass_install_dir\identity\oblix\lang\shared, Horizontalprofile.js includes the functions described in Table 2-24.

Table 2-24 Horizontalprofile.js

Function Name	Description
toggleImage	Change the image with the argument imageNam e to use the image from the argument srcName. This is a helper function for the change function.
change	Change the image specified by the arguments oldName, oldIndex to a new image specified by the argument newName, newIndex.
showPanel	Show the panel with the argument panel id name newPanel and argument panel id index newPanelIdx. In addition, the function hides the current panel.
initDynamicAuxClasses	Initializes the values of valuesOldName. Iterates through the elements in profileForm and stores the values of the named element oldName in the array valuesOldName. The argument oldName is the name of the element that stores the initial state of the set of auxiliary classes prior to the request. (The name used is ObOldAuxClasses).
diffAuxClassSet	Determine whether there is a difference in content between firstSet (the first argument) and secondSet (the second argument). Returns true if there is a difference, false otherwise.
isAuxClassChange	Determines whether or not a group type has been newly selected or removed. The current state of group types is stored in ObAuxClasses. The initial state is in ObOldAuxClasses. The method iterates over the elements of the profileForm and stores the values of any named newName elements if selected. It stores these values in valuesNewName. The method then compares valuesNewName to valuesOldName. If there is an element in valuesNewName not in valuesOldName or vice versa, then the state of auxiliary classes has changed. This method is used to determine the toggle state of the save image (either 'save' or 'update'). The argument newName is the name of the element that stores the current state of the set of auxiliary classes (the name used is ObAuxClasses). Returns true if there is a change in the state of the selected group types, false otherwise.
doSaveRequest	Does the save request action. This action can result in either the data being saved, or a request for the same page, if the user selected auxiliary classes whose attributes are not visible in the display. The argument oldName is the name of the element that stores the original state of the auxiliary classes. The argument newName is the name of the element that stores the current state of the auxiliary classes. The argument saveAction is the name of the action that results in the entry being saved. The argument moreAction is the name of the action that result sin a request for the same page with new attributes.
doToggle	This method toggles the image of the save button if the state of auxiliary classes has changed. It dynamically determines the source of the save button by looking up imageSave in the set of images in the document. It then re-sources the image by assigning a new image source to the save button element. The method looks up the image by comparing the value of its source. The argument oldName is the name of the element that stores the original state of the auxiliary classes. The argument newName is the name of the element that stores the current state of the auxiliary classes. The argument imageSave is the name of the save button image. The argument imageMore is the name of the more button image.

2.4.6.7 Misc.js

Located in WebPass_install_dir\identity\oblix\lang\shared, Misc.js includes the functions described in Table 2-25.

Note:

Oracle strongly recommends that you do not change mics.js. This is a system level file. It is contained in almost every stylesheet as an include file. Errors in this file affect most every stylesheet that the system uses. This becomes an insidious problem to solve. Customer Care cannot know if this file has been modified, and indeed, the customer may not know either. Changing this file can cause hidden problems, or problems down the road.

Table 2-25 Misc.js

Function Name	Description
obDetectBrowser	Detects the browser version of the client and set the proper variable.
submitFormAfter Confirm	Submits the form after the argument confirmation message is displayed.
submitLoginForm	Used for submitting the login form. Checks first to ensure the password is entered and then forms the proper URL for the next page - one that brings the user to the application selected.
checkPasswordEnterKey	Enable feature for allowing users to submit the login form when they press enter (or any other event specified in the argument). (For example, use this if you want to submit the login form when the user presses enter).
onUserType	For login form, reload the page when the user selects a different user type.
onApplication	For login form, if the user selected Publisher and optional authenticated view is disabled, then take the user to Publisher after the application selection.
setFocusToFirst TextElement	Set the focus of the argument form to the first element.
submitForm	Submit the first form in the page.
submitSpecifiedForm	Submit the form whose name is specified in the argument formName.
submitFormAfterUser Action	Submit the form with the action equal to the argument form. If the form action is activateForm, then additional confirmation messages are displayed.
submitFormCheckProfil eAttributes	Function used for checking whether the same profile attribute has been selected more than once. The application's logging policy modification screen uses this.
submitFormCheckCommonLogParams	Function used for checking whether numeric value is entered for log file maximum size.
isInteger	General purpose function to determine if the value entered is an integer.
IsNumeric	General purpose function to determine if the value entered is composed of digits.
isFloat	General purpose function to determine if the value entered is float.
isNonNullInteger	General purpose function to determine if the value entered is composed of integers. The difference between this function and the isInteger function is that this function does NOT return false if the input value is empty.
sendtotop	Set the current page to top.
IsStringOblix Compliant	Check to make sure the argument element is a non-empty string that does not contain , or ; or \. If it does, then an error message using the argument message is displayed.
isEmpty	Check if the argument string is empty or contains white space.
denyWithAlert	Display an alert message using the argument message.
checkAndSubmitForm	Submit the form if the argument does not equal "login". If the argument equals "passwd", then time out.
validateInput	Validate the following inputs: rootDN: ensure it is not empty. ldapRootPasswd: ensure it is not empty. machineNo: ensure it is not empty. portNo: ensure it is an integer. searchBase: ensure it is not empty. If all validation succeeds, pop up a final confirmation box for the change and submit the form.
validateSearch	Ensure that the display field record is a valid integer and that it is not empty.
checkSearchKey	Submit the form and perform proper validation for the forms deactUserSearchForm, searchForm, ObSearchGroupMembersForm, viewGroupMembers, and monitorsearchform.
validateSearchAndSubmit	Used by start search, more fields and less fields in the search functionality to do submit the form. For start search, validation (of the minimum number of characters for the search criteria values) is performed. For more field and less field, calculations of the number of rows required is calculated and then the form is submitted.
continueSearch	Used by the next and back buttons in the search functionality to submit the form. For next, it ensures that this is not already the last set of records. For back, it ensures that this is not already the beginning of the records.
continueSelectorSearch	Used by selector search next and back buttons. Submit the form after calculating the startFrom value.
doSearch	Submit the search form after assigning the proper values for sortBy and sortOrder, which are both provided as input arguments.
appendElementsTo BackUrl	Append a set of element_name=value pairs to the backUrl. The argument backUrl is the back URL string. The argument elements is the set of elements to append.
startTrim	Trim the beginning whitespace in the argument string.
endTrim	Trim the trailing whitespace in the argument string.
createBackUrl	Create and return the portion of the back URL that contains the forms elements. Append element/value pairs from all forms in the HTML document including those within layers.
PersonSelector	Used to launch the selector. The argument gotoUrl is the (selector) URL we're about to go to. The argument returnUrl is the URL you must use to get back to the page that invoked the selector.
QueryBuilder	Used to launch query builder. The argument gotoUrl is the (selector) URL we're about to go to. The argument returnUrl is the URL you must use to get back to the page that invoked the selector.
sendBookmark	Used for sending the search results as a bookmark.
validateLicenseKeys	Ensures that the form values are not empty. If the form values are empty, pops up an error message saying you must enter the license key.
validateLicenseKeysAnd Submit	Ensures that the form values (expected to be the license key values) are not empty and then submits the form.
lostPassword	Invokes the lost password functionality after ensuring that the login field is not empty.
certLicenseMessage	Pops up a message to warn the user to install the certificate management license file before any function is enabled.
installIECert	Calls a Virtual Basic Script function to install an x509 certificate. If you are using Netscape, it contacts the common server and get a stream of binary certificate.
extractCert	Calls a Virtual Basic Script function to install an x509 certificate.
performOCSP	Calls back to the modify profile page to use OCSP (Online Certificate Status Protocol) for certificate online checking. Before the URL is directed, it pops up an alert to warn the users that the OCSP checking takes a while.
validateDeactivatedUser Search	Ensures that the display record for the deactUserSearchForm is a non-empty integer.
validateGroupMember SearchAndSubmit	Validates group member search by calling validateGroupMemberSearch. If this is an update member functionality, a pop up message shows to confirm the changes before the form is submitted.
validateGroupMember Search	Do validation for group member search, such as ensuring that the minimum number of characters for each search value is satisfied and that the display record is a non-empty integer.
cancelWorkflow	Terminate the current workflow. Upon confirmation, go to the argument URL.
GetCookie	Retrieve the value of the cookie with the argument name.
setFocusToOKButton	Set the focus to the form element that is equal to javascript:top.close() for Internet Explorer 4 and Netscape 6.
submitFeedBack	Submit the feedback form.
checkJavaPlugin	Check to make sure that the proper java plug-in is installed.
EnableDetectJava PluginLayer	Enable the layer called "DetectJavaPlugin".
EnableJavaPlugin VersionLayer	Enable the layer called "DetectJavaPluginVersion".
DetectPluginForApplets	Verify that Java plug-ins are installed.
getParameterValue	Retrieve the value of the parameter in the URL with the argument name.

2.4.6.8 Miscsc.js

Located in WebPass_install_dir\identity\oblix\lang\shared, Miscsc.js includes the functions described in Table 2-26.

Important:

Oracle strongly recommends that you do not change Miscsc.js. This is a system level file. It is contained in almost every stylesheet as an include file. Errors in this file affect most of the stylesheets. This becomes an insidious problem to solve. Support cannot know if this file has been modified, and you may not know, either.

Table 2-26 Miscsc.js

Function Name	Description
SCConfirm	Submit the profile form. The argument value program is assigned to the profileForm program field by default or, if an argument message is not empty, then upon confirmation from the user through the pop up confirmation message.
SCRequestChangeAnd Submit	Submit the profile form after setting the program field to workflowChangeAttributeRequest. The argument attr determines the attribute for the change attribute request and the argument action determines whether this is a remove or change request.
SCRequiredValuesAlert	Provide an alert to the user saying that the required number of values (specified by the argument num_req) for the field ob_name (another argument) is not met.
SCPasswordNoConfirm	Alert the user that the password values specified by the argument ob_name do not match.
SCCheckSingleForm	Perform validation for each field within the form and alert the user if the validation is not satisfied. Otherwise return true. Sample validation includes checking that password matches, number of required values are met, and so on.
SCCheckForm	Check all forms on the page to make sure they satisfy the validation requirements.
SCSwitchProfile	Switch between horizontal and vertical modify profile by switching stylesheets.
SCSubmit	Submit the form by first performing all the validation. For the different types of actions (for example, save, less_values), additional logic is applied, such as pop up messages displayed and additional information sent back to the Identity Server.
getElementIndex	Returns the index of the element elementName in the form, or -1 if elementName is not found.
CopyElements	Assigns the value of elements in formFrom to the element of the same name in formTo.
hasKeyGenForm	Make sure the NavGenKeyform form is present.
InvokeKeyGen	A helper function that submits the NavGenKeyform.
AppendFormElements	Appends all the elements from all forms in all layers within the document to the input parameter form. form is in most cases the profileForm which is the form that is submitted. This method assigns the value of each element of each form within each layer to the identically named element in form. This method does not yet handle all special case display types; currently only checkbox is handled.

2.4.6.9 Monitorwf.js

Located in WebPass_install_dir\identity\oblix\lang\shared, Monitorwf.js includes the functions described in Table 2-27.

Table 2-27 Monitorwf.js

Function Name	Description
startSearchAndSubmit	Validate the monitorsearchform and then submit it.
continueSearch	Called when the user clicks the back and next buttons in monitor search results. If next is pressed, first checks if we are on the last record set, if so signals an error, otherwise, submits the form. If back is pressed, first checks if we are on the first set of records, if so signals that we are already at the beginning, otherwise, submits the form.
doSearchAndSort	Called to sort the search results for monitor search results using the arguments sortBy and sortOrder to perform the sorting.
submitresults	Called to purge/archive/unlock a workflow.
toggleselect	Toggle the search results form checkboxes from false to true.

2.4.7 Unspecified Program Names

For some screens, usually the most basic ones, the URL may not contain the program name. The program name can always be determined by generating and capturing the OutPutXML using format=XML. The stylesheet name is included at the top of the resulting file.

Behavior with the result varies with different versions of Microsoft Internet Explorer. For consistency, use Netscape Communicator and save the output as a text file, using an xml extension. You can then view this file with any text editor to get the stylesheet name.

2.5 Customizing Oracle Access Manager

XSL stylesheets give you the ability to place almost any component or piece of data almost anywhere on a page. This is more of an art than a science, and this Guide does not attempt to give precise instructions for getting the presentation you want. Instead, the following discussions outline the recommended approach for a minor change using the default Classic Style as a foundation.

Task overview: Customizing styles

1. Complete the "Prerequisites to Customizing Styles".

2. Review the "Customization Facts".

3. Review the "Customization Guidelines".

4. Familiarize yourself with the "Customization Methodology Checklist".

5. Complete the task "Customizing the Identity System Pages" to gain first-hand experience with customization and testing to debug your process.

6. See also, Chapter 4, "Modifying Catalog Files".

2.5.1 Prerequisites to Customizing Styles

Be sure to complete the following prerequisites before you start to customize a style. This enables you to keep the original Classic Style (\style0) intact for reference and in case you need to return to it as a last resort.

To prepare to customize styles

1. As an Identity Administrator, add your own named style as described in the Oracle Access Manager Identity and Common Administration Guide.

   The original style stays in effect until an Identity Administrator makes your style the new system default.

2. As an Identity Administrator, select the new style as the default style so that you can see the effect of any changes you make.

2.5.2 Customization Facts

Style Updates and Maintenance: Default wrapper files in \style0 and default global stylesheets in \shared are periodically updated to instantiate improvements through patches and product upgrades.

The Release Notes notify you when such updates occur so you can propagate the changes to your custom styles. Oracle recommends that you compare the new file with your custom file and propagate any changes to your custom styles. It is risky to overwrite a default style with a customized style that bears the same name.

Be sure to record the changes you make and the files that are involved so you can more quickly update custom stylesheets when you update default styles.

Custom Directory: Stylesheet customization should occur only within your custom directory. Customized stylesheets must reside in your custom directory and relative pointers in all files must point to the files in your custom directory, not to files in \shared.

Registration Files: As discussed in "General Content of Registration Files", a common registration file and each application's registration file contain the names of the stylesheets and schema files needed to present pages for the application. For example, when you look at the User Manager registration file in identity\oblix\apps\userservcenter\userservcenterreg.xml, you can see the application name and the names of the stylesheets the application calls during the completion of various functions.

Also, given the application and the program name, you can locate the corresponding schema file name in the application's registration file.

Oracle recommends that only experienced developers using extreme care consider editing a registration file. Registration files are covered in more detail at "Registration Files".

Pointers: All wrapper files and stylesheets contain pointers as include statements that call another file. Most of these pointers are relative pointers that indicate where within the directory structure the file is without providing an absolute path name.

For example, when you look at the usc_profile.xsl stylesheet called by User Manager functions, you can see that it contains include statements with relative pointers that call the following files:

./basic.xsl

./selectorinfo.xsl

./usc_searchform.xsl

./usc_navbar.xsl

When you change the location of a file (place a copy of a stylesheet in your custom directory for customization), pointers to this file (whether relative or absolute) must be changed to reflect the new location in every file that calls it. All relative pointers in a stylesheet should point to files in your custom directory.

In addition, many stylesheets contain relative pointers to object files. If Oracle Access Manager cannot instantiate an object when the page is loaded, unexpected behavior may result. All relative pointers to object files should be absolute pointers, as discussed in "Editing Stylesheets".

Wrapper Files: Wrapper files include pointers to actual stylesheets in \shared. However, you cannot be assured that a wrapper file is called before the stylesheet because both the common registration file and the application's own registration file call stylesheets according to an internal ordering. For this reason, all wrapper files in your custom directory must be overwritten by a copy of the corresponding default stylesheet from the \shared directory.

Important:

Customizing stylesheets is an iterative process. Attempting to copy the entire contents of \shared into your custom directory at one time produce an error.

Rather than copying all stylesheets at once, you start by investigating registration files to learn which functions (programs) call which stylesheets. You then selectively copy base stylesheets and a function-related stylesheet into your custom directory to overwrite their wrapper files, as discussed in "Copying Stylesheets to Your Custom Directory". You then customize and test the style for that function. When this returns satisfactory results you repeat the process to customize another function.

2.5.3 Customization Guidelines

The following guidelines should help ensure a successful customization.

• Retain all original files in the \style0 and \shared directories in pristine condition and store them safely for future use. Also, make a backup copy of your customized style files so that patches won't disrupt your customization.

• Record all changes you make and the files that are affected.

• Customize and test your new styles in a non-production environment before migrating them to your production environment.

  Important:

  Oracle recommends that you do not modify original style files in the \shared or \style0 directories. These may be overwritten by patch updates and product upgrades or you may want to refer to them later.

• When you use only one style, consider breaking the dependence on stylesheets in the \shared directory (again, to prevent patch\release updates to \style0 and \shared from disrupting customizations). This means that no stylesheet in your custom directory should inherit from or reference a stylesheet in \shared or \style0.

• When you use multiple custom styles, consider the pros and cons of sharing customizations between multiple custom styles with implementing individual customizations for each custom style. For example:

  • Two styles that share the same stylesheet: When two custom styles (custom_style1 and custom_style2) can share the same stylesheet you may be tempted to customize the stylesheet in the \shared directory despite the risk of having your custom style overwritten by an updated stylesheet in a product patch or upgrade.

  • Two individual styles: When two custom styles (custom_style1 and custom_style2) require their individually customized stylesheets you use the standard methodology and overwrite the wrapper files in your custom directory with the corresponding stylesheets in \shared.

• Consider using parameter stylesheet files for a custom style collection, rather than using hard-coded values (tab id's, attribute names, table/link properties, and so on); this is similar to how program code is written using header files.

2.5.4 Customization Methodology Checklist

As mentioned earlier, customization is an iterative process and more of an art than a science. This Guide does not attempt to give precise instructions for getting the presentation you want. Instead, this section outlines the recommended approach for a minor change.

Important:

Oracle recommends that you focus on stylesheets for one function at a time. Attempting to copy all stylesheets from \shared into your custom style directory results in an error.

Table 2-28 Customization Methodology Checklist

Check	Action	Description
	Add a New Style	See the Oracle Access Manager Identity and Common Administration Guide for details about adding a style and selecting your new style as the default.
	Choose a Function to Customize	Decide which function to customize first. Oracle recommends that you customize stylesheets related to one function at a time.
	Copy Selected Stylesheets into Your Custom Directory	Copy selected stylesheets from \shared to your custom directory to overwrite corresponding wrapper stylesheets: Base stylesheets Stylesheets included in base stylesheets A function-related stylesheet identified in application registration file Function-related stylesheets identified in oblixbasereg.xml
	Customize Stylesheets in Your Custom Directory	Change relative pointers in copied stylesheets to point to files in your custom directory. Change relative pointers to objects to absolute pointers. Complete other changes to implement the function's customization.
	Record Your Work	Keep a record of the files you change and the changes you make.
	Copy Your Custom Directory Structure to WebPass	Build a custom directory structure on WebPass and copy customized styles and images into it. Note: On WebPass, stylesheets are used only for client-side processing and are not required for server-side processing.
	Test Your Customized Style	Test the customized style and make any alterations you need to the stylesheets in your custom directory. Record the changes.
	Customize Another Function	Repeat this process on a function by function basis: Choose a function. Copy related stylesheets from \shared to your custom directory. Customize pointers and styles. Record and test your work.
	Propagate the Customized Style	When you have copied and customized all stylesheets for the application, copy the custom style directory to all Identity Servers and WebPass hosts in your environment.

2.6 Customizing the Identity System Pages

This example shows a method for changing the way a page looks, without changing what it does. The change is a simple font color alteration for a specific page in one application. After making the change you must verify that the change is successful. When you finish this functional customization, you must create the same custom style directory structure on WebPass and copy all image files into it so WebPass can display the appropriate images in response to queries. You then test the implementation.

The following topics demonstrate one sequence in the "Customization Methodology Checklist". You can complete the following procedures to gain first-hand experience:

Task overview: Customizing Identity System pages includes

1. Completing Prerequisites

2. Choosing a Function to Customize

3. Copying Stylesheets to Your Custom Directory

4. Editing Stylesheets

5. Copying Images and Styles to WebPass

6. Testing Your Customized Style

7. Propagating Styles

See also:

For details about localizing messages, see "Localizing XSL Files".

2.6.1 Completing Prerequisites

A prerequisite to customizing a style is to add a style and select the new style as the default, as described in the Oracle Access Manager Identity and Common Administration Guide. The resulting files and file structure provide the foundation for your customization.

Suppose you added a new style named Pastel in a directory named Pastel and requested files be copied from Classic Style (in directory \style0).

To confirm the results of adding a new style

1. Add a style and select it as the default, as described in the Oracle Access Manager Identity and Common Administration Guide.

   New Custom Directory: Oracle Access Manager creates a directory that duplicates \style0 for the default language, English. If you have installed a Language Pack for French, Oracle Access Manager also creates a directory that duplicates \style0 in the French language directory.

2. Locate your new custom directory.

   For example:

   Identity_install_dir \identity\oblix\lang\en-us\Pastel

   Identity_install_dir \identity\oblix\lang\fr-fr\Pastel

   Wrapper Stylesheets: Your custom directory contains wrapper stylesheets that point to actual stylesheets in another directory. If you selected the Classic Style to copy from, your custom directory duplicates the content of the \style0 directory.

3. Open a wrapper stylesheet in your new custom directory, basic.xsl, and review the files that it includes.

   For this example:

   Identity_install_dir\identity\oblix\lang\en-us\Pastel\basic.xsl

   <?xml version="1.0" ?> 
   - <!--    Copyright (c) 1996-2005, Oracle Inc. All Rights Reserved.  
     --> 
   - <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:oblix="http://www.oblix.com/">
     <xsl:include href="./style.xsl" /> 
     <xsl:include href="../msgctlg.xsl" /> 
     <xsl:include href="../../shared/basic.xsl" /> 
     </xsl:stylesheet>
   

   The basic.xsl wrapper stylesheet includes the following three files:

   • style.xsl file in your custom directory

   • msgctlg.xsl, one directory up from your custom directory (in identity\oblix\lang\en-us)

   • basic.xsl in identity\oblix\lang\shared

4. Locate and review the content of the basic.xsl stylesheet in \shared.

   For example:

   Identity_install_dir\identity\oblix\lang\shared\basic.xsl

   <?xml version="1.0" ?> 
   - <!--   Copyright (c) 1996-2002, Oblix Inc. All Rights Reserved. --> 
   - <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:oblix="http://www.oblix.com/">
     <xsl:include href="obstringutil.xsl" /> 
   - <!--  xsl:output indent="no"/ --> 
     <xsl:include href="font.xsl" /> 
     <xsl:include href="title.xsl" /> 
   ...
   

   The basic.xsl stylesheet in the \shared directory includes additional files (font.xsl, title.xsl, obstringutil.xsl) and provides templates to define attributes and status and control display information. See "basic.xsl" for more information.

   During your customization process, you copy selected stylesheets from the \shared directory into your custom directory. This overwrites wrapper files with corresponding stylesheets you can then edit in your custom directory.

   New Custom XML Document: In addition to the custom directory structure, when you select the new custom style as the default style, Oracle Access Manager creates an XML document (a duplicate of style0.xml) named after the directory you created.

5. Locate and open the custom xml document that was created when you added the new style.

   For this example:

   Identity_install_dir\identity\oblix\config\style\Pastel.xml

   <?xml version="1.0" ?> 
   - <ParamsCtlg xmlns="http://www.oblix.com" CtlgName="style0"> 
   - <ValNameList ListName=""> 
   <NameValPair ParamName="styleReady" Value="TRUE" /> 
   </ValNameList> 
   </ParamsCtlg>
   

   This new file, stored with style0.xml, provides the status of your custom style and the location of the original style directory from which wrapper files were copied. For example, if your custom style directory is named Pastel and you copied from Classic Style, the Pastel.xml file is created when you select Pastel as the default style.

   You do not need to edit this file. The original style0.xml remains unchanged. Also, there is a .lck version, Pastel.xml.lck, which is a lock file. No other new files are created when you add a new style.

   Updated styles.xml: The styles.xml file is updated to include a new NameValPair that provides both the directory and style names you supplied when creating the style.

6. Locate and open the styles.xml file to confirm it was updated with your new style information.

   For example:

   Identity_install_dir\identity\oblix\config\style\styles.xml

   <?xml version="1.0" encoding="ISO-8859-1" ?> 
   - <ValNameList xmlns="http://www.oblix.com" ListName="styles.xml"> 
   <NameValPair ParamName="style0" Value="Classic Style" /> 
   <NameValPair ParamName="Pastel" Value="Pastel" /> 
   </ValNameList>
   

   In this example, both the default Classic Style and new custom Pastel style are identified. You do not need to edit this file.

   After confirming your custom directory structure, new and updated files, you are ready to choose a function and begin your customization.

2.6.2 Choosing a Function to Customize

The first step in the customization process is to choose a function to customize. For this example, suppose you want to change the font color to red on a specific page of the User Manager without changing anything else.

To identify the function and source information

1. Log in to the Identity System, as usual.

2. Navigate to the desired page.

   For this example, click:

   Identity System Console, User Manager, and then click My Identity

   The page appears, as shown in Figure 2-6.

   Figure 2-6 Customization Example: A User Manager Page Displays Red Text

   
   

   The following information on each Identity System application page is useful for customizing styles:

   • Application Name: The application name, User Manager, appears on a highlighted tab in the top left area of the screen.

     Each application's \bin directory contains the registration file that you need to identify functions. See "Registration Files".

   • Page Name: The page name, in this example it is My Profile, is the first page that you want to customize so you can see text in a red font color.

   • Registration File Path: The URL for each page includes a path to the application page, for example, identity\oblix\apps\userservcenter\bin\userservcenter.cgi. You can use this to locate the relevant registration file on the Identity Server.

   • Function Name: The URL for each page also includes a segment, program=view in this case, that you can use to locate the relevant stylesheet name for the function in the registration file.

3. Record the required information to assist you during the customization.

   For this example:

   Application: User Manager

   Page: User Profile

   Registration File Path: Identity_install_dir\identity\oblix\apps\userservcenter\bin\

   Function: program=view

2.6.3 Copying Stylesheets to Your Custom Directory

Once you have identified the function you want to customize, your next task in any customization is to copy relevant stylesheets into your custom directory from the \shared directory. This activity overwrites wrapper files in your custom directory with copies of stylesheets you can customize. This also retains the original stylesheets in \shared as well as the original default wrappers in \style0.

Locating and copying relevant stylesheets is an iterative process in itself. In the following procedure you must locate and copy:

• Base stylesheets

• Stylesheets included in base stylesheets

• The specific function-related stylesheet identified for the program in the application's registration file, in this case the stylesheet associated with program=view

• Stylesheets included in the function-related stylesheet

Eventually your custom directory must contain all stylesheets, including those identified in the application's registration file and in oblixbasereg.xml. Even if you do not need to edit a stylesheet, it must be copied to your custom directory.

Important:

Copying stylesheets is an iterative process that must be done in a selective manner. Attempting to copy all stylesheets from \shared to you custom directory at one time results in an error.

To locate and copy relevant stylesheets

1. Copy the base stylesheets to your custom style directory from \shared to overwrite the default wrappers with stylesheets you can customize.

   For example:

   Copy from: Identity_install_dir\identity\oblix\lang\en-us\shared\ basic.xsl, font.xsl, searchform.xsl, navbar.xsl, title.xsl

   Copy to: Identity_install_dir\identity\oblix\lang\en-us\Pastel\

   This retains the original base stylesheets in \shared as well as the original default wrappers in \style0.

2. Open each base stylesheet in your custom style directory and locate include statements that point to other stylesheets you must copy, as well as any style information you need to customize.

   For this example, see Table 2-29:

   Table 2-29 Base Stylesheet Pointers and Items to Customize

   Base Stylesheets in Custom Directory	Pointers to Related Stylesheets and Items to Customize
   basic.xsl	Contains implied relative include pointers to other stylesheets you need in your local custom directory: <xsl:include href="obstringutil.xsl" /> <xsl:include href="font.xsl" /> <xsl:include href="title.xsl" /> Record the names of additional stylesheets you must copy into your custom directory from \shared. In this case, obstringutil.xsl.
   font.xsl	Does not contain include pointers to other files. Does contain color information you can customize: <xsl:variable name="subHeadingColor">#006699... <xsl:variable name="contentTitleColor">#000000... <xsl:variable name="contentTextColor">#000000...
   searchform.xsl	Does not contain include pointers to other files. Does not contain color information to customize. No changes needed to this stylesheet in your custom directory.
   navbar.xsl	Does not contain include pointers to other files. Does contain color information you may customize later.
   title.xsl	Does not contain include pointers to other files. Does contain color information you may customize later. No changes needed to this stylesheet in your custom directory.

   
   

3. Copy stylesheets included in base stylesheets to your custom directory from \shared.

   For this example, obstringutil.xsl:

   Copy from: Identity_install_dir\identity\oblix\lang\en-us\shared\ obstringutil.xsl

   Copy to: Identity_install_dir\identity\oblix\lang\en-us\Pastel\obstringutil.xsl

4. Record the stylesheets you have copied from \shared to your custom directory so you can track your work.

5. Locate the required registration files.

   For this example, oblixbasereg.xml and userservcenterreg.xml:

   Identity_install_dir\identity\oblix\apps\common\bin\oblixbasereg.xml Identity_install_dir\identity\oblix\apps\userservcenter\bin\ userservcenterreg.xml

   At some point, you typically need stylesheets included in the common registration file oblixbasereg.xml. However, stylesheets included in oblixbasereg.xml are not needed for this example.

   For this example, you must locate only the function-related stylesheet in the userservcenterreg.xml file.

6. Open the application's registration file and locate the function-related stylesheet you need.

   For this example, locate ObProgram name="view":

   <?xml version="1.0" ?> 
   - <ObProgramRegistry>
      - <ObApplication name="userservcenter">
         - <ObProgram name="front">
             <ObStyleSheet name="usc_profile.xsl" /> 
             <ObSchema name="usc_front.xsd" /> 
         </ObProgram>
         - <ObProgram name="commonNavbar">
              <ObStyleSheet name="usc_profile.xsl" /> 
              <ObSchema name="usc_front.xsd" /> 
           </ObProgram>
   ...
      - <ObProgram name="view">
         <ObStyleSheet name="usc_profile.xsl" /> 
         <ObButton name="initiateDeactivateUser" /> 
         - <!-- ObButton name="manageSubscriptions"/ --> 
         <ObButton name="userreactivate" /> 
         <ObButton name="wfTicketDelete" /> 
         <ObButton name="userModify" /> 
         <ObSchema name="usc_profile.xsd" /> 
      </ObProgram>
   ...
   

   You can see in the registration file that the usc_profile.xsl stylesheet is associated with the function you want to customize (ObProgram name="view"). The usc_profile.xsl stylesheet is also associated with a number of other functions.

7. Copy the function-related stylesheet, usc_profile.xsl, to your custom style directory from \shared and record the stylesheet name.

   For this example:

   Copy From: Identity_install_dir\identity\oblix\lang\en-us\shared\ usc_profile.xsl

   Copy To: Identity_install_dir\identity\oblix\lang\en-us\Pastel\ usc_profile.xsl

8. Open the function-related stylesheet and locate include statements that point to other stylesheets you must copy, record any information you plan to customize.

   For this example, usc_profile.xsl:

   Table 2-30 usc_profile.xsl Pointers and Items to Customize

   usc_profile.xsl in Custom Directory

   Pointers to Related Stylesheets and Items to Customize

   usc_profile.xsl

   This main stylesheet for the User Manager includes stylesheets that must be copied to your custom directory: <xsl:include href="./basic.xsl" /> <xsl:include href="./selectorinfo.xsl" /> <xsl:include href="./usc_searchform.xsl" /> <xsl:include href="./usc_navbar.xsl" /> Note: selectorinfo.xsl, usc_searchform.xsl and usc_navbar.xsl should be copied. Also record pointers to objects that should be customized: <object id="cenroll" classid= ... codebase="../../common/bin/xenroll.cab" /> and <script src="../../common/bin/installCert.vbx" ...

   
   

9. Repeat steps to copy relevant stylesheets, then record their names and details you plan to change.

   For this example:

   Copy From:

   Identity_install_dir\identity\oblix\lang\en-us\shared\selectorinfo.xsl

   Identity_install_dir\identity\oblix\lang\en-us\shared\usc_searchform.xsl

   Identity_install_dir\identity\oblix\lang\en-us\shared\usc_navbar.xsl

   Copy To:

   Identity_install_dir\identity\oblix\lang\en-us\Pastel\selectorinfo.xsl Identity_install_dir\identity\oblix\lang\en-us\Pastel\usc_searchform.xsl Identity_install_dir\identity\oblix\lang\en-us\Pastel\usc_navbar.xsl

   These stylesheets do not contain include statements, other stylesheet names, nor parameters you need to change.

   You have collected, copied, and recorded relevant stylesheets for this example.

2.6.4 Editing Stylesheets

After copying relevant stylesheets, you may need to edit them. As described in Table 2-29 the information that needs to be customized for this example includes:

• Font colors defined in the base stylesheet font.xsl should be changed to red.

• Pointers to objects defined in usc_profile.xsl should change from a relative path to an absolute path.

Note:

To help streamline development and testing, consider implementing XSL stylesheet control parameters. See "Caching Considerations".

To edit stylesheets for a simple font color change

1. Open the font.xsl stylesheet in your custom directory in a text editor.

   For example,

   Identity_install_dir\identity\oblix\lang\en-us\Pastel\ font.xsl

2. Edit the stylesheet to change all colors from the default color to red (FF0000), then save the change.

   For example,

   Change all Default Font Colors From:

   ... <xsl:variable name="pageHeaderColor">#006699</xsl:variable> 
   <xsl:variable name="subHeadingColor">#006699</xsl:variable> 
   <xsl:variable name="contentTitleColor">#000000</xsl:variable> 
   <xsl:variable name="contentTextColor">#000000</xsl:variable> 
   and others ...
   

   To Red (#FF0000):

   ... <xsl:variable name="pageHeaderColor">#FF0000</xsl:variable> 
   <xsl:variable name="subHeadingColor">#FF0000</xsl:variable> 
   <xsl:variable name="contentTitleColor">#FF0000</xsl:variable>
   <xsl:variable name="contentTextColor">#FF0000</xsl:variable> 
   and others ...
   

3. Record your changes to this file.

   If you restarted the Identity Server now you would not yet see your changes. This is because you have not yet customized the function-related stylesheet that identifies where to apply the changes.

4. Edit the basic.xsl stylesheet in your custom directory as follows to add required include statements that were in the original basic.xml (but were lost when you copied over the basic.xsl from the shared folder).

   1. Locate the line containing the following:

      <xsl:include href="obstringutil.xsl"/>
      

   2. Add the following information so that it precedes the line identified in a):

      <xsl:include href="./style.xsl" /> 
         <xsl:include href="../msgctlg.xsl" />
      

5. Edit the usc_profile.xsl stylesheet in your custom directory to change the relative path to objects, as shown in the following, then save the changes.

   For example:

   Change From a Relative Path:

   - <head> 
   ...<object id="cenroll" classid="clsid:43F8F289-7A20-11D0-8F06-00C04FC295E1" codebase="../../common/bin/xenroll.cab" /> 
   ... <script src="../../common/bin/installCert.vbx" language="VBScript" /> 
   </head>
   

   Change To an Absolute Path:

   - <head> 
   ... <object id="cenroll" classid="clsid:43F8F289-7A20-11D0-8F06-00C04FC295E1" codebase="/identity/oblix/apps/common/bin/xenroll.cab" /> 
   ... <script src="/identity/oblix/apps/common/bin/installCert.vbx" language="VBScript" /> 
   </head>
   

   This concludes the specific function-related change for this example.

6. Ensure that file system access control for new custom style directories and files is set to match the ownership and permissions of \style0.

7. Restart the Identity Server.

   If you log in to the Identity System now and view the My Identity page, you see the red font color. However, the images supplied by WebPass won't appear until they are included in a corresponding custom style directory structure on the WebPass host.

2.6.5 Copying Images and Styles to WebPass

Images and JavaScript are served by the Web server that the WebPass is installed against, not by the Identity Server. When a style refers to an image, the image is served by WebPass. If the image does not exist in the WebPass file hierarchy, the image appears as a broken link. To avoid this, you must create a custom style directory on WebPass and include all images in this structure, whether you are adding new images or using default images.

To copy images to WebPass

1. Copy your custom style directory from the Identity Server to WebPass.

   For example:

   Copy From: Identity_install_dir\identity\oblix\lang\en-us\Pastel

   Copy To: Identity_install_dir\identity\oblix\lang\en-us\Pastel

   Note:

   Stylesheets are included on WebPass for use with client-side processing only. Stylesheets are not required on WebPass for server-side processing.

2. Copy all image files from \style0 on WebPass to your custom directory on WebPass, whether you are using default images or adding new images.

   For example:

   Copy images From: WebPass_install_dir\identity\oblix\lang\en-us\style0

   Copy images To: WebPass_install_dir\identity\oblix\lang\en-us\Pastel

   Note:

   This example does not include new images. Only default images called by the new custom style. If custom images are included, copy those to the custom directory as well.

3. Restart WebPass.

You are ready to test your customized style.

2.6.6 Testing Your Customized Style

You are ready to test your customized style and make any changes needed to achieve satisfactory results.

For testing purposes, the XSLProcessor parameter indicates the processor to use when generating the page. See "XSLProcessor" for details.

Note:

To help simplify development and testing, you may want to implement XSL stylesheet control parameters, as discussed in"Caching Considerations". You may use an XML editing environment to allow testing stylesheet customizations offline, as discussed in Chapter 7, "Useful Tools".

If you don't obtain the desired result, check the items in "Troubleshooting Customization Issues".

To test your style

1. Log in to the Identity System, as usual.

2. Navigate to the page you customized.

   For example:

   Click User Manager, and then click My Identity

3. Confirm that the font color now displays in red, as shown in Figure 2-7.

Figure 2-7 Customization Example: A User Manager Page Displays Red Text

2.6.7 Propagating Styles

When you know your style is working, you can push this out to other Oracle Access Manager systems.

To propagate styles

1. Copy your custom style directory from the Identity Server to all other Identity Servers.

2. Restart each Identity Server.

3. Copy your custom style directory from the WebPass host to all other WebPass hosts.

4. Restart each WebPass.

2.6.8 Troubleshooting Customization Issues

If you obtain unexpected results, check the following items to ensure that you have completed all tasks correctly.

• Have you added a new style and selected this as the default style?

• Have you identified and copied relevant stylesheets to your custom directory from \shared (see application and common registration files):

  • Base stylesheets

  • Stylesheets included in base stylesheets

  • The specific function-related stylesheet identified in the application's registration file.

  • Stylesheets included in the function-related stylesheet?

  • Relevant stylesheets in the common registration file?

• Have you made appropriate changes to stylesheets in your custom style directory?

  • Relative pointers to stylesheets

  • Relative pointers that should be absolute pointers to objects

  • Other customization details

• Have you created a duplicate custom style directory structure on WebPass?

• Have you copied images to your custom style directory structure on WebPass?

  Note:

  Oracle Access Manager relies on these images. Oracle recommends that you copy the files to your custom directory. On rare occasions that your custom image does not appear but the default does, you may need to change the default image.

• Have you restarted the Identity Server and WebPass?

See also:

For more information, see "Troubleshooting Example".

2.6.9 Localizing XSL Files

As discussed elsewhere, multiple languages are available for use with version 7.0 and higher. Messages that were once in stylesheets are language dependent and are now defined separately as variables in message catalogs. The new directory structure consolidates all message catalogs for JavaScript files, XSL, and HTML.

• Any language-specific files are located in \lang\langTag.

• Any non-language specific objects are located within \lang\shared.

All the stylesheets have a language-specific wrapper in \lang\langTag\style0 which includes the main language-neutral version stylesheet in \lang\shared. This new wrapper segregates the main stylesheet functionality, which is language independent, from language-specific messages.

Language-specific messages are referred to through variables in message catalog files, as discussed in:

Display names for the Identity applications are stored in the stylesheet. For localization, these display names must be translated for the each language that your organization supports.

For example, the display name User Profile is stored as an XSL variable "MUserProfile" in:

Identity_install_dir\identity\oblix\lang\en-us\msgctlg.xsl file

The XSL variables are stored in the XSL stylesheet, for example usc_profile.xsl, located in Identity_install_dir/identity/oblix/lang/shared.

To localize XSL files

1. Store the display name text strings in a separate file as XSL variables.

2. Reference them in the stylesheet.

2.7 Verifying XSL Files

To verify that a stylesheet is coded correctly, open it in Internet Explorer. The browser indicates the line number of any errors in the code.