Chapter 1   Installation and Administration


iPlanet Application Server Enterprise Connector for PeopleSoft enables you to build interactive web-based applications that accesses data stored in a PeopleSoft database. These web-based applications might be for electronic commerce, or for any management, financial, distribution, and manufacturing of a supply chain within an enterprise system. Specifically, iPlanet Application Server Enterprise Connector for PeopleSoft enables you to manipulate data within a PeopleSoft transaction from a servlet or Enterprise JavaBeans (EJB) controlled by the iPlanet Application Server.

This chapter describes concepts the administrator should be familiar with when setting up iPlanet Application Server Enterprise Connector for PeopleSoft or using the Application Programming Interfaces (API) in servlets or EJBs, and contains the following:

• Overview

• Installing the Enterprise Connector for PeopleSoft

• Mining the PeopleSoft Message Definition

Overview

---

The Enterprise connectors fit into a three tier application model setup that supports the iPlanet Application Server Enterprise Connector for PeopleSoft 6.0 web server setup.

Figure 1-1    Application Model

The three tier application model is composed of the following:

• Presentation Tier

• Application Server Tier

• Data Access Tier

Presentation Tier

The presentation tier is where information is accessed by the user, usually a web browser. The user accesses iPlanet Application Server from his browser using HTML via HTTP and HTTPS (1).

Application Server Tier

The application server tier (2) houses the intelligence for the web server, applications, and communications to databases such as Oracle, DB2. Enterprise Java Beans (EJB) and servlets are supported by the iPlanet Application Server. In addition, iAB and iEB Tools provide ways to create EJB's and servlets, which are accessed by the Unified Integration Framework (UIF), as seen in the Data Access Tier.

Data Access Tier

The data access tier consists of the UIF which provides business logic needed to enable uniform access to different backend systems (3). The function of the UIF is to act as an interpreter to ease the transfer of information. The UIF interfaces with EJBs and servlets on one side, and product-specific Enterprise connectors on the other side. This tier also works closely with the Mining Tool, which is provided by the iPlanet Application Server Enterprise Connectors and is used to convert metadata to XML, and to populate the UIF Repository.

The UIF is composed of two parts:

• Application Programming Interface (API) framework

• UIF Repository

API Framework

The API framework is an API that enables the client to talk to the backend systems. Information exchange occurs at this stage. iPlanet Application Server Enterprise Connector for PeopleSoft uses a unique system to communicate with the backend system. The PeopleSoft Worker is a single threaded function that is created by the SRVDAEM daemon. A daemon is a special program that is not directly invoked, but remains dormant until a special condition arises when it is invoked. A request from the browser is routed through the iPlanet Application Server Enterprise Connector for PeopleSoft server (1), which exits the connector to the PeopleSoft PeopleSoft Worker. The SRVDAEM is contacted, which invokes a PeopleSoft Worker (3). The worker then exchanges information between the Message Agent and the connector (4). More workers are created and connected as needed.

Figure 1-2    API Framework

UIF Repository

The UIF Repository is particularly sensitive to data in XML format. The UIF is actually a consistent way to access backend data. It is an API that communicates with the backend system.

An EJB calls for various commands/information from the backend system. This call is routed through the UIF, which serves as a translator between the backend system and the EJB. A dialog is established, an exchange of information occurs, and the dialog is concluded. See Figure 1-1 Application Model.

The Mining Tool uses a common cross-platform format, XML, to populate the repository by taking backend information such as PeopleSoft Message definitions, and converting it to XML. The XML is then stored in the UIF Repository in a specific structure that can be recalled when necessary.

Figure 1-3    Mining Tool

Enterprise Connector for PeopleSoft Architecture

• Unified Integration Framework (UIF), a common Application Programming Interface (API) used to access data. For example, programmers use the UIF API to query different databases with one set of calls.

• PeopleSoft-independent core services module.

• The PeopleSoft Worker, which facilitates the connection between the repository and iPlanet Application Server Enterprise Connector for PeopleSoft.

• A repository that contains data that drives iPlanet Application Server Enterprise Connector for PeopleSoft. The repository is associated with the UIF to hold parameters and other information about the PeopleSoft system; for example, the kind of connection, the data that can be accessed, and the access methods.

• A connector that implements the PeopleSoft-specific data access services. The connector provides the translation and packaging of data between the UIF and the PeopleSoft system.

The following describes the components in a typical iPlanet Application Server Enterprise Connector for PeopleSoft system

Servlet	The Servlet is an application that operates the iPlanet Application Server Enterprise Connector for PeopleSoft.
UIF API	The common UIF API that enables you to operate different Enterprise connectors with the same API.
Enterprise connector	The component in iPlanet Application Server Enterprise Connector for PeopleSoft that enables you to access the PeopleSoft packet. The function of the connector is to act as an interpreter to ease the transfer of information.
Repository	A specialized structure where all the PeopleSoft message definitions are stored for the use of iPlanet Application Server Enterprise Connector.
PeopleSoft Management Console	The Graphic User Interface (GUI) that enables you to perform various administrative tasks.
PeopleSoft Metadata Mining Tool	This component enables you to introspect from within the Management Console to the PeopleSoft backend system.
Repository Browser	The repository browser enables you to view the Repository and its components. See the iPlanet Application Server Enterprise Connector for PeopleSoft Developer's Guide for further details.
PeopleSoft System (Message Agent)	A PeopleSoft native component that enables you to access PeopleSoft.

:

Technical Overview

In this section, we will discuss the following topics:

Prerequisites	This section describes existing conditions or required installed programs to run the iPlanet Application Server Enterprise Connector for PeopleSoft.
Development	This section describes method definition and servlet application.
Deployment	This section describes how to arrange the application.
Run Time	This section describes the various actions that occur during the run time.

Prerequisites

To properly run the iPlanet Application Server Enterprise Connector for PeopleSoft, the following requirements must be met:

• You must install iPlanet Application Server Enterprise Connector for PeopleSoft and UIF (see Chapter 2, iPlanet Application Server Enterprise Connector for PeopleSoft Administrator's Guide).

• You must configure a connection to the backend system. In Windows NT, you must have a path to the PeopleSoft's client dll file. In SOLARIS, you must set the following environment variables: LD_LIBRARY_PATH, and PS_HOME.

• Message definitions must be created using the PeopleSoft Application Designer tool (see iPlanet Application Server Enterprise Connector for PeopleSoft Developer's Guide, Chapter 3, Programming Examples).

Development

The PeopleSoft servlet application development includes the following:

• From the Management Console, from the Data Mining option, mine one or more of the Message Definitions defined in the backend and activated via the Message Agent (see Management Console in the iPlanet Application Server Enterprise Connector for PeopleSoft Developer's Guide).

• Use the PeopleSoft mining tool found in the Management Console.

• Write a servlet application using recently mined methods. Write an application or call the function object yourself using direct UIF API (see iPlanet Application Server Enterprise Connector for PeopleSoft Developer's Guide, Chapter 3 Using the UIF API Directory).

Deployment

This section describes how to strategically arrange the application or servlet.

To properly deploy the application, you need to:

1. Register the application.
   To register a servlet in iPlanet Application Server 6.0 you need to create two XML files. Name the XML thoughtfully, as the name of the XML file is used as a lookup to run the servlet. For example, if you name the XML "test.XML", then you may want to create a file named "ias-test.XML". Access the servlet from an HTML page as follows: /NASApp/<xmlfilename>/<servletname>.

   For example, consider the following two files as viewed through a simple editor:
   
   

   The first file is named "float_disp.xml". The other file is named ias-float_disp.xml". They are similar. They differ in the prefix "ias-" added to the second sample.

   
   
   

2. Use the servlet registration tool to register the application.
   Type webappreg <XML file name (without the prefix "ias-")>

3. Restart the application server.

Copying Files to Another iPlanet Application Server Installation

1. Create a zip file of the function directory with the PeopleSoft function name; e.g. ProcessMsg.zip.

2. Copy the zip file to the other machine.

3. Open the zip file to the directory \ias\APPS

4. Load the XML files with the data mining tool.

5. The directory will always contain <function_name.XML> and may also contain <ECUstructure.XML>.

6. Go to the directory.

7. Register the server using the command: webappreg <filename.XML> package.

8. Restart the application server.

RunTime

The following processes occur during the run time flow:

1. The servlet is executed by HTML via a URL or a JSP.

2. The servlet Java code starts a PeopleSoft function object in the iPlanet Application Server Enterprise Connector for PeopleSoft through the UIF API.

3. The PeopleSoft connector retains all the input definitions from the repository.

4. The PeopleSoft connector executes a request against the PeopleSoft backend, sending the received input. When a reply is received from the PeopleSoft backend system, the PeopleSoft connector returns the reply to the UIF, which then returns all the output values to the servlet Java code. This is then sent back via HTML to the user.

Installing the Enterprise Connector for PeopleSoft

---

First the iPlanet Application Server must be installed. For information, please see the iPlanet Application Server, Version 6.0, Installation Guide.

There are two iPlanet Application Server Enterprise Connector for PeopleSoft installations. One for Windows NT, and Solaris.

Installing on Windows NT

The following describes the procedure for installing and uninstalling iPlanet Application Server Enterprise Connector for PeopleSoft on Windows NT.

In addition:

• Installation Prerequisites

• Installation Procedure

• Uninstalling iPlanet Application Server Enterprise Connector for PeopleSoft for Windows NT

Installation Prerequisites
The iPlanet Application Server Enterprise Connector for PeopleSoft 6.0 installation requires that the following be resident on your system: an appropriate web server, such as iPlanet Enterprise Server (iES) version 4.1, iPlanet Application Server 6.0, and the Unified Integration Framework (UIF) module.

In addition, iPlanet Application Server Enterprise Connector supports PeopleSoft Version 7.55.

Before beginning the installation:

1. Check that an appropriate web server, iWS 4.1 or later, has been installed.

   If your system does not have an installed web server, install one before beginning the iPlanet Application Server 6.0 installation. The disk size requirements for the web server are in addition to the requirements listed in the table below.

2. Check that iPlanet Application Server 6.0 is installed on your system.

   iPlanet Application Server 6.0 must be installed on your system before you start the iPlanet Application Server for PeopleSoft 6.0 installation. See the iPlanet Application Server Installation Guide for instructions on installing iPlanet Application Server 6.0.

3. Check that UIF 6.0 is installed on your system.

   UIF 6.0 must be installed on your system before you start the iPlanet Application Server for PeopleSoft 6.0 installation. See the iPlanet Application Server Installation Guide for instructions on installing iPlanet Application Server 6.0.

Minimum System Requirements

Operation System	Windows NT 4, Service Pack 5
Hard Drive	100 MB free for minimum installation; 150 MB is recommended.
iPlanet Application Builder (Optional)	100 MB
iPlanet Application Server	150 MB
RAM	64 MB; 128 MB is recommended

4. Make sure that the following environment variables are set to the appropriate pointers:

   PATH	This must point to a directory that contains the PeopleSoft client's DLL files.
   In Solaris: PS_HOME LD_LIBRARY_PATH	This must point to the PeopleSoft client home directory. The directory must also have a subdirectory named: tuxedo.

Installation Procedure
Unzip the iPlanet Application Server for PeopleSoft files.

1. Double-click on the setup.exe file.

2. Read the Welcome message and then click Next.
   
   

3. Read the License Agreement; click Yes if you agree,

   Thoroughly read and understand this information before installing.
   
   

4. Choose your installation directory, then click Next.

   If you are only installing iPlanet Application Server Enterprise Connector for PeopleSoft, you must install iPlanet Application Server for PeopleSoft in the same directory as you installed iPlanet Application Server.
   
   

5. Select the iAS for PeopleSoft 6.0 check box and then click on the Next button
   
   .

6. Type in all the requested information into the text boxes and click Next.

   This information defines your PeopleSoft Backend system.
   
   

7. Type in the appropriate values of your database machine.
   
   

   Type in the requested information in the text boxes and then click Next to continue with the installation.

---

Note	The Service and Type text boxes can be left blank.

---

8. 
   
   Review the configuration summary. If it is correct, press the Install button.

---

Note	If you have previously installed iPlanet Application Server 6.0 on your computer the following messages will be displayed. Click No To All to complete the installation.

---

9. The Setup File Copy window may appear. Click the button appropriate to your situation.
   
   

---

Caution

You must restart your computer after you complete the installation.

---

Uninstalling on Windows NT

This procedure is used to uninstall iPlanet Application Server Enterprise Connector for PeopleSoft.

Uninstalling the Enterprise Connector for PeopleSoft

1. Choose Uninstaller from the Windows NT start menu's programs - iPlanet Application Server 6.0 entry.

2. Deselect all components for iAS except iAS for PeopleSoft, then click OK.

   While deselecting the components for iPlanet Application Server, the uninstaller checks for dependencies between components.

Deselecting
Deselect items in the following order:

1. Deselect iPlanet Server Family Core components.

2. Deselect Administration Services and iPlanet Directory Suite.

3. Deselect iAS 6.0.

Deselecting iPlanet Application Server
Click Change and deselect options in the following order:

1. Deselect Application Server 6.0 core binaries.

2. Deselect Web Connector Plug-in component

3. Deselect Administrator's component.

4. Deselect Deployment Manager component.

5. Deselect core Server component.

---

Caution

If you do not follow the above mentioned order of deselections, alert messages will be displayed and you may not be able to deselect the desired option.

---

Installing on Solaris

Here are the installation steps for iPlanet Application Server Enterprise Connector for PeopleSoft on Solaris.

To ensure that you have everything necessary to complete the installation, review this section before starting the installation.

Installation Prerequisites

The following are required before you can install iPlanet Application Server Enterprise Connector for PeopleSoft.

• iPlanet Enterprise Server 4.1 or above installed

• iPlanet Application Server 6.0

• Unified Integration Framework

• PeopleSoft client libraries

Make sure that the following environment variables are set to the appropriate pointers:

---

LD_LIBRARY_PATH	This must point to a directory that contains the PeopleSoft libraries.
PS_HOME	This must point to the PeopleSoft client home directory. The directory must have a subdirectory named: tuxedo.

---

Pre-Installation

The first step in the pre-installation is to download and unzip the file inspsft.zip to a temporary directory.

Ensure that the same setup is used for installing iPlanet Application Server.

Installation Procedure

1. In the temporary directory type Type#./setup

   The following message appears:

   Sun-Netscape Alliance
   iPlanet Server Products Installation/Uninstallation

   Welcome to the iPlanet Server Products installation program

   This program will install iPlanet Server Products and the

   iPlanet Console on your computer.

   It is recommended that you have "root" privilege to install the

   software.

   Tips for using the installation program:

   • Press "Enter" to choose the default and go to the next screen

   • Type "Control-B" to go back to the previous screen

   • Type "Control-C" to cancel the installation program

   • You can enter multiple items using commas to separate them.

     For example: 1, 2, 3.

     Would you like to continue with installation? [Yes]:

2. Type Yes to continue.

   The following message appears:

   BY INSTALLING THIS SOFTWARE YOU ARE CONSENTING TO BE BOUND BY AND ARE BECOMING A PARTY TO THE AGREEMENT FOUND IN THE LICENSE.TXT FILE. IF YOU DO NOT AGREE TO ALL OF THE TERMS OF THIS AGREEMENT, PLEASE DO NOT INSTALL OR USE THIS SOFTWARE.

   Do you agree to the license terms? [No]:

   If you agree with the terms of the agreement

3. Type Yes to continue.

The following message appears:

Select the items you would like to install:

iPlanet Servers

Installs iPlanet Servers with the integrated Netscape Console onto your computer.

Netscape Console

Installs Netscape Console as a stand-alone Java Application on your computer.

To accept the default shown in brackets, press the Enter key.

Select the component you want to install [1]:

4. Press <Enter> to install the iPlanet Server.

   The following window appears:

   This program will extract the server files and install them into a directory you specify. That directory is called the server root in the product documentation and contains the server programs, the Administration Server, and the server configuration files.

   To accept the default shown in the brackets, press <Enter>.

   Install location [/iPlanet/iAS6]:

5. Type the iPlanet Application Server installation directory, and then press <Enter>.

   The following message appears:

   iPlanet Server Products components:

   Components with a number in () contain additional subcomponents

   which you can select using subsequent screens.

   1. iAS PeopleSoft Adapter 6.0

   Specify the components you wish to install [1]: 1

6. Press <Enter> to install all the components.

The following message appears:

Enter the fully qualified domain name of the computer

on which you're installing server software. Using the form

<hostname>.<domainname>

Example: eros.airius.com.

To accept the default shown in brackets, press the Enter key.

Computer name [grass.tel-aviv.israel.sun.com]:

7. To accept the default shown in brackets, press the <Enter> key.

The following message appears:

Choose a Unix user and group to represent the iPlanet server

in the user directory. The iPlanet server will run as this user.

It is recommended that this user should have no privileges

in the computer network system. The Administration Server

will give this group some permissions in the server root

to perform server-specific operations.

If you have not yet created a user and group for the iPlanet

server, create this user and group using your native UNIX

system utilities.

To accept the default shown in brackets, press the Return key.

System User [nobody]:

System Group [nobody]:

8. To accept the default shown in brackets, press the <Enter> key.

The following message appears:

Please enter the PeopleSoft host name.

Host Name:

9. Type in the Host Name.

   The following message appears:

   Please enter the listener port.

   Listener Port:

10. Type in the Listener Port identification.

    The following message appears:

    Please enter the user ID and password.

    User ID:

    Password:

11. Type in the User ID and Password.

    The following message appears:

    Please enter the Oracle host name.

    Host Name:

12. Type in the Oracle host name.

    The following message appears:

    Please enter the listener port.

    Listener Port:

13. Type in the Listener Port ID.

    The following message appears:

    Please enter the database SID.

    Database SID:

14. Type in the database SID.

    The following message appears:

    Please enter the user ID and password.

    User ID:

    Password:

15. Type in the User ID and Password.

The following message appears:

Finished with gathering of information.

Next, the iAS for PeopleSoft files will be extracted. After that,

the configuration and registration based on your responses will begin.

Please hit ENTER to continue:

16. Press <Enter> to continue.

After the successful installation on Solaris to view the samples, use the Application Designer tool provided by PeopleSoft to define a Message Definition (see iPlanet Application Server Enterprise Connector for PeopleSoft Developer's Guide). You may find the samples by going to the URL: http://<machine.mcom.com>/psftSamples.

Uninstalling on Solaris

1. If you want to uninstall the iPlanet Application Server Enterprise Connector for PeopleSoft, go to the installation directory, [iPlanet/ias6]

2. Type ./uninstall.
   A list of uninstall options appears.

3. Select the specific product components you wish to uninstall.

Mining the PeopleSoft Message Definition

---

The iPlanet Application Server Enterprise Connector for PeopleSoft does a specialized form of data mining: it looks at data and extracts functions and parameters from backend systems to enable iPlanet Application Server Enterprise Connector for PeopleSoft users to utilize (call) these functions. To do this, the Management Console is used.

Entering the Management Console from Windows NT

Select Start>Programs>iPlanet Application Server 6.0>PEOPLESOFT Connector 6.0 - Management Console.

Figure 1-4    Windows NT Entry

Entering the Management Console from Solaris

1. Run: psconsole.sh

   from <iPlanet inst directory>

2. Select the PeopleSoft Management Console icon, and click the Open button in the upper right to display the PeopleSoft Management Console.
   
   

Figure 1-5    PeopleSoft Management Console window

Data Mining

Data mining is the search for relationships and global patterns that exist in large databases. These relationships represent valuable knowledge about the database and objects in the database. The elements of the Data-mining tool are shown in the following illustration.

Figure 1-6    Data Mining Elements

You submit search criteria to the Management Console which queries PeopleSoft for any functions matching the criteria. You then select the function or functions to be mined. Data is extracted from PeopleSoft, converted to XML, and then loaded into the repository.

Displaying the Data Mining Selections

1. Click the Data Mining icon to display the Choose Data Source list.
   
   

Figure 1-7    Choose Data Source window

2. Optional step: Click on the Detail button to view the Data Source Details dialog box. The data in this window is read only. Click the OK button to return to the Choose Data Source window.
   
   

Table 1-1 Data Source Details

Field	Definition
Database Login Name	The user name.
Database SID	Database system identifier.
Database Host	Name of the Oracle database host.
Database Port	Name of the listening port of the Oracle database.
PeopleSoft User Name	PeopleSoft user name.
PeopleSoft Host Address (name port)	Name of the listening port of the PeopleSoft database.

3. Select the Data source and then click the OK button to display the list of Activities and Message Definitions
   
   

   
   

   ---

   Note	This is a list of Activities and Message Definitions. You must use the Application Designer tool as provided by PeopleSoft to create your own Message Definitions.

   ---

   
   

4. Select the Message Definition(s), and click on the Convert button to create an XML file(s) and load it into the repository.

   
   

   ---

   Note	The default option, stored in a directory with the name of the activity, can not be changed.

   ---