Change directory to $WSHOME/bin then set permissions
on the files in the directory so that they are executable.

Step 3: Configure the Waveset Database Connection

Note –

If you plan to use a database, you may need to copy one or more
files to the idm/WEB-INF/lib directory. For example, you
may need to place a JAR file containing a JDBC driver (for a DriverManager
connection) or a JAR file containing a JNDI InitialContextFactory (for a DataSource
connection). To determine the steps you may need to perform before you go
on, see the Appendix C, Database Reference.

The ServerRepository.xml file
is an encrypted file that defines how to connect to the repository. Use one
of the following procedures to configure the repository XML file.

To Configure the Repository XML file in Windows or
Xwindows (UNIX) Environments

Enter one of the following commands to launch the setup interface.

On Windows

cd %WSHOME%\bin
lh setup

On UNIX

cd $WSHOME/bin
lh setup

The installer displays a welcome page. Click Next to display the Locate
the Repository panel.

Enter or browse for the init.xml file (located
in the idm/sample directory), and then click Import.

Step 4: Install Optional Components

If your IT environment has Windows Active Directory, Novell NetWare,
Domino, Remedy, or RSA ACE/Server resources, you should install the Waveset Gateway.

If your IT environment has Windows Active Directory domains,
you should also install PasswordSync. The Waveset PasswordSync
feature keeps user password changes made on Windows Active Directory domains
synchronized with other resources defined in Waveset.

Appendix C Database Reference

If you plan to use a database, you may need to copy one or more files
to the idm/WEB-INF/lib directory on your application server
during the Waveset installation process. The following table shows
the download or installed product location of one or more .jar files
that you need to copy for your database type.

Notes on Configuring Databases and Downloading Supporting
JAR Files

Note –

For any given database, there should only be one JAR file with
JDBC drivers installed at any given time. When installing JAR files, inspect WEB-INF/lib and remove any JAR files that contain conflicting JDBC
drivers. For example, if installing a JAR file containing Oracle JDBC drivers,
remove the Oracle JAR file that you are replacing before starting Waveset.

Databases that are managed resources also utilize
JDBC driver JAR files located in the WEB-INF/lib directory.
The same JAR file that supports your repository will also support any managed
database resources from the same vendor.

Tip –

To help avoid conflicts when installing JDBC driver JAR files,
Oracle recommends renaming JAR files using the format dbNamejdbc.jar. The name of the JAR file does not matter, but renaming
a .jar file to include the name of the database followed
by jdbc is recommended to help administrators avoid JAR
file collisions in the future.

Database

Download or Product Location

Configuration Notes

DB2

Db2/java/db2java.zip

—OR—

If you are using the Type 4 network driver, use this file instead:

db2jcc.jar

If you are using at least DB2 8.1.2, you will also need the following
files:

Enter the database location and the password you selected when you set
up the database.

Note: All connections to SQL Server
must be performed using the same version of the JDBC driver. This includes
the repository as well as all resource adapters that manage or require SQL
Server accounts or tables, including the Microsoft SQL adapter, Microsoft
Identity Integration Server adapter, Database Table adapter, Scripted JDBC
adapter, and any custom adapter based on these adapters. Conflict errors occur
if you attempt use different versions of the driver.

LocalFiles

Path:c:\jakarta-tomcat\webapps\idm\config

Enter the directory location, or click Browse to locate it.

Directory Server (Sun Java System Directory
Server)

Initial Context Factory:com.sun.jndi.ldap.LdapCtxFactory

URL:ldap://host.your.com/dc=myDomain,dc=your,dc=com

User:waveset

Enter the database location. Optionally enter the password you selected
when you set up the database.

Appendix D Configuring Data Sources for Waveset

This appendix provides procedures for creating data sources for Waveset.

Change the -f location flag to the value you
specified for the Resource name attribute, above. The prefix java:/com/env is specific to javaURLContextFactory and
Tomcat. This is the JNDI prefix that the data source name is appended to.

Configure the Waveset webapp to use the data source by
copying the new ServerRepository file in place. For example:

When you copy the data-source-enabled ServerRepository.xml to $WSHOME/WEB-INF, the lh command
will stop working. This is expected because lh uses ServerRepository.xml to connect to the Waveset repository. Since lh is
not running in the Tomcat container, it cannot look up the data source in
Tomcat's JNDI.

When a Tomcat data source is used by Waveset, the
data source will typically be responsible for connection pooling. In this
case Waveset connection pooling needs to be disabled. Edit the RepositoryConfiguration configuration object and set the disableConnectionPool attribute
to true to allow the Tomcat data source to manage the connection
pool.

The concurrent use of the lh utility and
Tomcat data sources can be problematic because of the connection pool issue
mentioned above. Tomcat data sources will want to control the connection pool,
but the lh utility cannot use the Tomcat data source, so
the value of the RepositoryConfiguration disableConnectionPool attribute will depend on the type of access, either JDBC or data
source.

Configuring a WebSphere Data Source for Waveset

Use the following information to configure a WebSphere Data Source for Waveset.

Servlet 2.3 Data Sources

As of the Waveset 6.0 release, the deployment descriptor in
the WEB-INF/web.xml file refers to Servlet 2.3. Because
of this, the Waveset web application can no longer be used with a
WebSphere application server version 4 data source.

Note –

Due to interoperability issues between WebSphere data sources
and Oracle JDBC drivers, Oracle customers who want to use a WebSphere data
source with Waveset must use Oracle 10g R2 and the corresponding JDBC
driver. (The Oracle 9 JDBC driver will not work with a WebSphere data source
and Waveset.) If you have a version of Oracle prior to 10g R2 and
cannot upgrade Oracle to 10g R2, then configure the Waveset repository
so that it connects to the Oracle database using Oracle’s JDBC Driver
Manager (and not a WebSphere data source).

To Configure a WebSphere Data Source for Waveset

Configure a JDBC provider.

Configure a WebSphere JDBC Data Source.

Point the repository to the data source.

These steps
are discussed next.

Configuring a JDBC Provider

To Configure a JDBC Provider

Before You Begin

Use WebSphere’s administration console to configure a new JDBC
Provider.

Click the Resources tab in
the left pane to display a list of resource types.

Click JDBC then JDBC Providers to display a table of configured JDBC
providers.

Click the New button above
the table of configured JDBC providers.

Select from the list of JDBC database types, provider types, and
implementation types. Optionally modify the Name and Description fields.

Oracle, Oracle JDBC Drive, and Connection pool Data Source will be used
for this example.

Click Next.

Enter database classpath information. The contents of the Enter database class path information page may vary,
depending on what you selected in the previous step.

Specify the path to the JAR that contains the JDBC driver.
For example, to specify the Oracle thin driver, specify a path similar to
the following:

Complete any other fields as required. The selected database,
provider, and implementation types determine which fields are displayed. Click Next when you have completed the dialog.

A summary page is displayed. When you are finished reviewing
your selections, click the Finish button
at the bottom of the table. Click the Save link
to keep your definition. The right pane should display the provider you added.

Enter a unique alias, a valid user ID, a valid password, and a
short description (optional). The user ID must be valid on the target database.

Click OK or Apply. No validation for the user ID and password
is required.

Click Save.

Note –

The newly created entry is visible without restarting the application
server process to use in the data source definition. But the entry is only
in effect after the server is restarted.

To Configure the Data Source

Click Resources > JDBC Providers > Your_JDBC_Provider_Name > Data Sources tab in the left pane to display the
Data sources page. The right pane displays a table of data sources configured
for use with this JDBC provider. Click the New button
above the table of data sources.

Use the wizard provided to configure the general properties for
the new data source. Note the following on the Enter basic data source information
page:

The JNDI Name is the path
to the DataSource object in the directory service. You must specify this same
value as the -f argument in setRepo -tdbms-iinitCtxFac-ffilepath.

Select the Component-managed Authentication
Alias that you created in Configuring a JDBC Provider. These are the credentials that will be used to access
the DBMS (to which this DataSource points).

Click Next when you have configured this panel. The Create
New JDBC provider page is displayed.

Configure the database-specific properties for this data source
as needed. Refer to the online help for information about the available properties.

Make sure Use this data source in container-managed
persistence (CMP) is unchecked. Waveset does not use Enterprise
Java Beans (EJBs). Click Next to go to the summary page.

Click Finish to save your data
source.

Configure the Data Source in a WebSphere Cluster

When configuring the data source in clustered WebSphere environments,
configure it at the cell level. This allows the data source to be accessed
from all nodes in the cell.

To configure this use the -D$propertiesFilePath option where $propertiesFilePath contains:

java.naming.provider.url=iiop://localhost:jndi_port/

or:

-u iiop://localhost:jndi_port/

To Determine the JNDI Port to Specify

Examine the WebSphere configuration to determine the JNDI port to specify.

Look at the BOOTSTRAP_ADDRESS property.
Use the specified port in the java.naming.provider.url property.

Note –

The java.naming.provider.url uses localhost as the hostname. WebSphere replicates a JNDI server on each node
in the cluster so that each application server has its own JNDI server to
query. Specify localhost for the host so
that each application server in the cluster is used as the JNDI server that Waveset queries
when the DataSource is being located.

Point the Waveset Repository to the Data
Source

To Point the repository to a Newly Created Data Source

Set the WSHOME environment variable to point to your Waveset installation;
for example:

export WSHOME=$WAS_HOME/installedApps/idm.ear/idm.war

where $WAS_HOME is the WebSphere home directory,
such as /usr/WebSphere/AppServer

Make sure that the JAVA_HOME environment variable is set correctly;
for example:

export JAVA_HOME=$WAS_HOME/java

Make sure that the Java executable is in your path; for example:

export PATH=$JAVA_HOME/bin;$PATH

Make sure the classpath is pointing to the WebSphere properties
directory. For example

export CLASSPATH=$WAS_HOME/properties

Change to the $WSHOME/bin directory.

(For SQLServer only): Install JTA support:

Copy the sqljdbc.dll file located in the SQLServer JTA directory to the SQL_SERVER_ROOT/binn directory
of the SQLServer database server.

In the above example the DataSourcePath might be jdbc/jndiname.
The -Djava.ext.dirs option adds all of the JAR files in
WebSphere’s lib/ and java/jre/lib/ext/ directories
to the CLASSPATH. This is necessary in order for the setRepo command to run normally.

Change the -f location flag to match the value you
specified for the JNDI Name field when
configuring the data source. See Appendix F, setRepo Reference for more information about this command.

In the RepositoryConfiguration configuration object, set the connectionPoolDisable
attribute to true.

Restart WebSphere to pick up changes. (This also restarts the
system.)

Specifying Additional JNDI Properties to the setRepo Command

The setRepo command provides an option that allows
you to specify an arbitrary set of properties. The -D $propertiesFilePath option allows you to specify any number of settings, including
vendor-specific properties not specified by JNDI, by including them in a properties
file that you create.

For example, to specify a different JNDI port number, include a line
like the following in your properties file:

java.naming.provider.url=iiop://localhost:2909

Configuring a WebLogic Data Source for Waveset

Use the following procedure to update the repository configuration in Waveset to
point to a WebLogic Data Source.

Create a JDBC Data Source

To Create a JDBC Data Source

Expand the Services folder for the domain located in the navigation
(left) pane.

Expand the JDBC folder.

Expand the Data Source folder.

In the right pane (JDBC Data Sources), click Configure a new JDBC Data Source.

Configure the JDBC Data Source as follows:

Value

Action

Name

Choose a unique name for this data source. This name is used as a reference
throughout the WebLogic Console. For example, MyOraDataSource.

JNDI Name

Specify the JNDI name. This can be the same as the Data Source name.
For example MyOraDataSource.

Honor Global Transactions

Select this check box (selected by default) if you want to enable global
transactions using this data source (see WebLogic online help for more information
concerning this option). In this example we keep the default.

Click Continue.

Select the connection pool from
part A. This allows an application to get a connection from the underlying
connection pool.

Click Continue.

Select the servers on which you want deploy the new data source.

Click Create.

Note –

The configuration steps are saved in your WebLogic config.xml file for a given domain. Changes to the XML file appear as:

Point the Waveset Repository to the Data
Source

To Point the Waveset Repository to the Data
Source

Set the WSHOME environment variable to point to
your Waveset installation; for example:

set WSHOME=C:\bea\user_projects\domains\mydomain\applications\idm

Make sure that the JAVA_HOME environment variable
is set correctly; for example:

set JAVA_HOME=C:\j2sdk1.5

Make sure that your chosen database drivers are installed for
you Weblogic Server. See the WebLogic documentation for further information.
In this example, the Oracle drivers and classes12.jar are
installed in following directory:

If you enter this command when using the Data Direct JDBC Driver
for Oracle, the operation will fail with following exception:

java.sql.SQLException: [sunm][Oracle JDBC Driver]This driver is locked for
use with embedded applications.

The Data Direct JDBC Driver for Oracle that ships with Oracle Glassfish Server is “locked”
so that it works only with embedded applications. That is, the driver works
only within the web container. As a result, to use the lh command,
you must create a separate connection.

Archive the existing $WSHOME/WEB-INF/ServerRepository.xml file.

Use the following command to force the connection and create a
new ServerRepository.xml file:

Make a backup copy of the ServerRepository.xml file
located in %WSHOME%\WEB-INF (Windows) or $WSHOME/WEB-INF (UNIX).

Copy the new ServerRepository.xml config file
to %WSHOME%\WEB-INF (Windows) or $WSHOME/WEB-INF (UNIX).

Create a .war file from WSHOME

Copy the idm.war file to your server configuration.

Start the JBoss server.

Configuring an Oracle Application Server Data Source
for Waveset

Data source configuration can be performed entirely in the Oracle Enterprise
Manager 10g Application Server Control Console. The online help in the Application
Server Control Console provides useful information on data source settings.

Use the following procedure to update the repository configuration in Waveset to
point to an Oracle Application Server Data Source.

The -f location flag should match the value
you selected for the JNDI Name field.

If there are no reported errors, restart your Oracle Application
Server to pick up the changes. (This also restarts the Waveset system.)

Appendix E Changing the Database Repository Password

If you are using a DBMS (such as MySQL, Oracle, DB2, or SQL Server)
as the location for the Waveset repository, it may be necessary to
change the database connection password or username periodically. The procedure
for changing these values depends on how Waveset connects to the database.

Changing a Repository Password Stored in a Database

It is recommended that you perform each of these steps in the
order presented. If you change the repository password at a time other than
when directed in this sequence, problems can occur.

If Waveset connects to the repository with a JDBC driver, or
if it connects to the repository using a Data Source that does not contain
the connection user name and password, then use the following procedure to
change the user or password:

To Change a Repository Password Stored in a Database

Before You Begin

The examples used in this procedure are for a MySQL repository. Some
steps may vary depending on the specific repository used.

Archive a copy of the existing ServerRepository.xml file, in case you need
to revert to it. By default, this file is located in $WSHOME/WEB-INF.

If you have deployed Waveset in an application server
cluster, you should operate on the main source folder
for Waveset (from which the application server
deploys the IDM web application), rather than on each target folder
(to which the application server deploys the web application
on a particular server or node within the cluster).

Shut down Waveset. If you have deployed Waveset in
a cluster, then you must stop all instances of the web application across
the cluster.

Verify the existing repository:

lhsetRepo -c

Waveset responds with the current repository information; for
example:

MysqlDataStore:jdbc:mysql://localhost/waveset

Create a temporary file system repository location:

mkdir c:\tempfs

Set Waveset to use the temporary file system repository
location:

lh setRepo -tLocalFiles -fc:\tempfsLocalFiles:c:\tempfs

Change the password for your repository. This procedure depends
on the mechanism provided by your repository provider. This example highlights
steps for a MySQL database:

The warning message appears because the temporary file system
that you pointed to has no contents. Ignore this message; after running the
command, the temporary file system will no longer be needed.

Verify the new repository value:

lh setRepo
-c

The application responds with the new value:

MysqlDataStore:jdbc:mysql://localhost/waveset

Restart the server and verify that you can log in. If you have
deployed Waveset in a cluster, then you must re-deploy Waveset across
the cluster. This will distribute the updated web application (which includes
the updated ServerRepository.xml file), to all nodes in
the application server cluster.

Changing a Repository Password Stored in a Data Source

If Waveset connects to the repository using a JDBC
data source, and the data source contains the user name and password, then
use the following procedure to change the username or password.

To Change a Repository Password Stored in a Data Source

Stop Waveset. If you have deployed Waveset in
an application server cluster, stop the application on all hosts.

Change the password for the connection user name in the DBMS instance
that you are using as your repository location. For example, on MySQL

mysqladmin.exe -hlocalhost -uwaveset -poldpasswd password newpasswd

Change the password that is stored on the DataSource object using
the tools provided by the application server, directory server, or DBMS that
manages your DataSource object.

Re-start the server and verify that you can login. If you have
deployed Waveset in a cluster, then you must re-deploy Waveset across
the cluster. This will distribute the updated web application (which includes
the updated ServerRepository.xml file), to all nodes in
the application server cluster.

Appendix F setRepo Reference

The lhsetRepo command sets the Waveset repository
to the location specified.

Usage

setRepo [location_flags] [options]

location_flags

Flag

Description

-ddatabaseName

dbName in URL. The default name is waveset. Ignored
if the -u flag is specified.

-DpropsPath

Path to Properties file (JDBC/JNDI Connection Properties)

-ffilepath

Filesystem path for LocalFiles (JNDI RDN for DataSource)

-hhostName

Host name URL. Ignored if the -u flag is specified.

-iinitCtxFac

Name of the InitialContextFactory class for JNDI

-jjdbcDriver

JDBC Driver class. (The default is DBMS-specific.)

-pportNumber

Port number in URL. Ignored if the -u flag is specified.

-Ppassword

Password for JDBC connection.

-ttype

Oracle, MySQL, SQLServer, DB2, or LocalFiles

-u "url"or"-uurl"

URL for JDBC connection (overrides the -d, -h,
and -p flags)

-Uusername

User name for JDBC connection.

Options

Option

Description

-Aadministrator

Administrator username. The default username is configurator.

-Ccredentials

Administrator password (if changed from default)

-c

Current (print current location to stdout)

-v

Verbose (print configuration to stdout)

-n

No checks. Use with the –o flag when the new
location is unreachable, or with -c when current location
is unreachable from the command line environment.

-ooutfile

Output file path. Use this if the new location is unreachable. Write
the config file, but DO NOT update the server and DO NOT check the new location.

Syntax

Note –

If any parameters contain a shell escape or illegal characters,
use double quotation marks around them to avoid failures. For example, the ";", "&", "&&", "|",
and "||" characters cause these failures.

The following is an example containing arguments for a direct JDBC driver
connection:

Appendix G DBMS Recovery and the Repository

This chapter discusses strategies for backing up and recovering the
repository.

Recovering the Repository

Disaster recovery planning is an essential part of deploying any business-critical
system. Each supported DBMS has multiple mechanisms for data backup and restoration.
Any of these are appropriate. Waveset has no implicit requirements.

Typically, if a database fails, it would only be necessary to restore
the repository to the point just before the database failure. However, if
business requirements dictate that the repository be restored to any given
point in time (through use of the appropriate vendor-specific methods such
as ARCHIVELOG mode or Flashback in Oracle or FULL logging mode in SQL Server),
this can be done as well. Regardless of the recovery method used, it is necessary
to consider some implications of restoring a version of the repository that
is not completely up-to-date.

While the state of the repository will be self-consistent after the
data restoration, it will not necessarily be consistent (or even compatible)
with external objects such as the resources. The following items demonstrate
some possible inconsistencies that might arise:

Restored users might have pending attribute changes that are
no longer desirable, because of more recent changes.

Restored workflows and tasks might be in a state that no longer
matches the environment. For instance, formerly completed tasks could attempt
to run again, and approvals might re-appear, requesting action from an administrator.

Additionally, resources are themselves the repository of account attributes.
Restoring the repository to a specific point in time may not aid in restoring
resources to prior states, since the information required to do so may never
have been stored in the repository.

redo Logs

Point-in-time recovery methods require the existence of an unbroken
set of change records (typically referred to as “redo logs”).
This can often present logistical challenges if the rate of change is high,
generating a large volume of redo.

Waveset tries to minimize the need to write to the redo logs.
However, database activity cannot be completely eliminated. Even when Waveset appears
to be idle, each server polls the repository in order to detect changes to
repository objects, tasks ready to run, tasks ready to clean up, and so forth.

The intervals on which these activities occur are configurable, and
increasing these configured intervals will reduce the frequency of (but will
not eliminate) database operations that Waveset executes against the
repository when idle. To configure these intervals, define new values for
the cache.pollingInterval and other properties that begin
with cache and ChangeNotifier in the Waveset.properties file.

In addition, disable the listcache.size property
on any application server in a cluster that does not serve the Waveset Graphic
User Interface. Disabling this property reduces number of operations that Waveset executes
against the repository when the application is idle.

Appendix H Working with Firewalls or Proxy Servers

This chapter describes how Waveset uses Uniform Resource Locators
(URLs)
and how to configure Waveset to obtain accurate URL data when firewalls
or proxy servers are in place.

Servlet APIs

The Web-based Waveset user interface is highly dependent on
Uniform Resource Locators (URLs) to specify the location of pages to
be retrieved by the Web client.

Waveset depends on the Servlet APIs provided by an application
server (such as Apache Tomcat, IBM WebSphere, or BEA WebLogic) to determine
the fully qualified URL in the current HTTP request so that a valid URL can be placed in the generated
HTML and HTTP response.

Some configurations prevent the application server from
determining the URL the Web client uses for an HTTP request. Examples include:

A port-forwarding or Network Address Translation (NAT) firewall
placed between the Web client and Web server, or between the Web server and
application server

A proxy server (such as Tivoli Policy Director WebSEAL) placed
between the Web client and Web server, or between the Web server and application
server

For instances in which the Servlet APIs do not provide accurate URL
data from an HTTP request, the correct data can be configured in the Waveset.properties file (located in your Waveset installation config directory).