Chapter 1   Overview of the APIs


The Programmer's Reference Guide documents the public Java application programming interfaces (APIs) that are included in the iPlanet Portal Server product, as well as documents the exposed HTTP/XML interfaces.

The Programmer's Reference Guide offers information to any programmer customizing iPlanet Portal Server software. For example, use the Session and the Profile APIs to integrate the application with the iPlanet Portal Server software and utilize single signon capabilities, or the Content Provider modules for the user desktop.

---

Note	Detailed information on APIs is available in the Javadocs from http://yourserver-name:port/docs/en_US/javadocs/

---

Extending iPlanet Portal Server

---

iPlanet Portal Server can be extended in several ways, as illustrated in Figure 1-1. If additional authentication capabilities are needed use the Pluggable Authentication API to create them. To add Java based applications, use the Session, Profile and Policy, and Log APIs to integrate them into the iPlanet Portal Server framework. Finally, to have additional content providers in the iPlanet Portal Server desktop, use the Content Provider API (and optionally other APIs) to integrate the providers directly into the iPlanet Portal Server desktop.

Figure 1-1    End User Component Interaction Flow

The end user interacts equally with the iPlanet Portal Server components as configured by default and with additional components written to integrate with the iPlanet Portal Server software.

The iPlanet Portal Server APIs

---

Table 1-1 summarizes the APIs in iPlanet Portal Server software.

Table 1-1 The iPlanet Portal Server APIs 

API Name	Description
Profile and Policy	The Profile allows applications to access profile information, with the Profile and Policy API, stored on the iPlanet Portal Server. Profile information includes user preferences, application attributes, platform-wide attributes, and configuration information. Applications may define and store their own application-specific attributes and configuration with this API. The Policy provides some methods, in the Profile and Policy API, to determine user privileges.
Session	The Session API allows applications to verify whether a user has a valid session. When a user authenticates with the iPlanet Portal Server product, a session is created and stored on the iPlanet Portal Server. The Session API allows any application to validate the user's session and retrieve information about the session, such as the session state, the time remaining, and the user name.
Logging	The Log API allows applications to create, delete, write, and read logs and log records to and from the iPlanet Portal Server.
Content Provider	The Content Provider API provides methods for integrating content with the iPlanet Portal Server desktop.
Pluggable Authentication	The Authentication API allows the writing of a Java-based pluggable authentication module for iPlanet Portal Server software.

Writing programs that directly use the Java API is a far simpler and more efficient solution than using the exposed HTTP/XML interface, because the Java API "hides" the over-the-wire protocols, thus making implementation more straightforward.

The classes that can be included in the Java implementation automatically handle communication and data transfer with the iPlanet Portal Server. When considering a non-Java application, see Appendix A for a description of the processes, the communications protocols, the Document Type Definitions (DTDs), and other issues associated with applications that use the exposed HTTP/XML interface. Developers writing programs that will communicate with the exposed HTTP/XML interface to iPlanet Portal Server need to understand and be able to use eXtensible Markup Language (XML) and HTTP.

Which APIs to Use?

The iPlanet Portal Server APIs fall into several broad categories:

To do:	Use these APIs:
Application Development	Optionally use Profile and Policy, Session, and Logging.
Authentication Extension	Authentication, and optionally use Logging.
Desktop Extension	Provider, and optionally use Profile and Policy, Session, and Logging.

Understanding iPlanet Portal Server APIs

---

This section describes the development process for a sample iPlanet Portal Server desktop provider application that touches on the public APIs available for integrating an application with the iPlanet Portal Server desktop.

The following main steps outline the process:

1. Define high-level application requirements.

2. Determine which iPlanet Portal Server APIs support the high-level requirements.

3. Define the iPlanet Portal Server attributes.

4. Define the privileges that determine the policy for the application.

5. Create an XML file to define the provider to the iPlanet Portal Server desktop.

6. Import the XML file to the Profile server with ipsadmin.

7. Configure and modify the applications through the Administration Console.

A non-Java iPlanet Portal Server application cannot directly use the Java APIs, it must use the HTTP/XML interfaces that are defined in Appendix A, "HTTP/XML Interface". Each XML DTD specifies the content and format of the information that can be sent to and received from the iPlanet Portal Server services.

Identify Needed iPlanet Portal Server APIs

---

Applications can interact with as many or as few of the APIs as necessary to provide functionality. These application may be configured by the administrator, either at a domain/role level or at the user-level, and by the user through the standard desktop interface. Additionally, the configuration may be retained between sessions. The application may also log the configuration settings of a user every time they are changed, recording accesses to a corporate database, or any other legitimate logging function, or if there is no logging requirement then there is no need to use the Log API.

Content Provider API

The application may use this provider to:

• Display information in the provider's portion of the desktop

• Display a page to the user that allows setting configurations

• Handle the submission of the configuration parameters

Additional methods are provided to:

• Query information about the provider

• Set information for the provider

To use the default actions, just create a provider that will be imported into (registered with) the iPlanet Portal Server product.

Registering a provider with the iPlanet Portal Server product requires creating an XML file with the specific attributes and privileges for this provider and the "common" attributes that a provider may have to utilize the default methods.

To import the XML into the Profile server use the ipsadmin command, and then from the Administration Console register the provider to the iPlanet Portal Server software.

Profile and Policy API

Because a user's configuration should be retained between sessions, it is advantageous to store configuration parameters in the Profile server. To do this, define appropriate attributes/privileges to be imported via the provider's XML file and the ipsadmin Command. These attributes and privileges can be retrieved and modified through the Administration Console or the Profile and Policy API.

It is not a requirement to store anything in the Profile server, because a separate database or even just a flat file on the iPlanet Portal Server could be used, but using the profile server has some advantages:

• The profile server eliminates the need to create a new database and write access routines

• The profile server is hierarchal in nature, making it easy to set configuration parameters at a domain or role or user level

• In an iPlanet Portal Server configuration, with multiple servers, the Profile and Policy API will access the common profile server. When writing applications that use the Profile and Policy API, file locking and some database access functions are handled "behind the scenes" by the Profile and Policy API

• Simple "out of the box" administration of the provider's attributes and policy

Session API

The Session API is used to access information about a session. An iPlanet Portal Server session contains the information needed to get a profile from which to get/set attributes and will optionally check the policy to validate the iPlanet Portal Server user.

The Session API also provides methods to get:

• Client ID

• The domain

• Session type

• Idle time

• Session time

Log API

It is possible to write to a log file separate from the iPlanet Portal Server Log API, but using the Log API has some advantages:

• The Logging API provides some other useful log-management functions. For example, controlling the number and size of logs, that would have to be redeveloped if the API was not used

• The logs can be administered through the Administration Console, and access to the logs for any user is controlled by the Profile and Policy API

Integrating an Application with iPlanet Portal Server Software

---

When writing an application, privileges can be created to be associated with users and attributes and then be associated with uses and applications. For example, in a payroll application, create a privilege associated with viewing salary, or with changing salary, and create an attribute for a particular background color.

An overview of the sequence to integrate an application with iPlanet Portal Server software is as follows:

1. Identify data to be stored in the iPlanet Portal Server profile versus data that is to be obtained from other sources.
   Payroll data is probably stored in a payroll database, and it would not be appropriate or necessary to migrate this to the iPlanet Portal Server profile database. However, there is probably authentication information that the user must enter to access the payroll database. For example, a user name and password, could be defined as attributes in the iPlanet Portal Server profile. See Chapter 7, "Single Signon".

2. Decide which policy to assign for users whom access this application, and define corresponding privileges and default values.

3. Create an XML file that defines the data identified in Step 1 and Step 2.

4. Use the iPlanet Portal Server ipsadmin utility on the command line to import the XML and configure the Profile server to recognize the application.

5. Modify the application to use the iPlanet Portal Server APIs to identify the user rather than prompting for authentication information, when using a single-signon solution. This assumes that the application is already web-based. The code should:
   1. Use the Session API to translate an HTTP request from the user into an iPlanet Portal Server session.

   2. Use the Profile and Policy API to access the application-specific authentication information that is stored in the iPlanet Portal Server profile.

6. Use the Administration console to provide access to the payroll application.

7. Use the Administration console to configure the policy for different roles.