Chapter 4   Administering the Desktop Service

This chapter describes how to administer the Sun™ ONE Portal Server Desktop service.

This chapter contains these sections:

• Overview of the Desktop
• Overview of Hot Deployment of Channels
• Overview of Provider Archives
• Administering the Desktop Service
• Administering par Files

Overview of the Desktop

---

This section describes the Desktop component, its underlying structure, and how you administer it.

Desktop Glossary

Table 4-1 describes the pertinent Desktop terminology.

The first column of the table lists the term; the second column provides a definition of the term.

Table 4-1    Desktop Glossary

Term	Definition
Desktop	Provides the primary end user interface for Sun ONE Portal Server.
Provider	Generates content for a particular type of format (XML provider) or technology (JSP™) provider.
Channel	Displays content in the Desktop, usually arranged in rows and columns. At runtime, a channel consists of a provider object, configuration, and any data files (JSP, HTML templates, and so on) required to support the channel.
Container or Container Channel	A channel that primarily generates its content by including or aggregating the content of other channels (referred to as child channels).

Desktop Architecture and Container Hierarchy

The Desktop is the primary end-user interface for Sun ONE Portal Server. It is implemented through a servlet and is supported by various APIs and utilities (for example, iPlanet™ Directory Server Access Management Edition APIs, resource bundles, properties files, back-end servers such as mail, and so on).

The Desktop provides a mechanism for extending and aggregating content through the Provider Application Programming Interface (PAPI). Content providers, or providers, enable container hierarchy and the basic building blocks for building some types of channels. Usually, channels are arranged in rows and columns, but they can also be displayed in some other arrangement, depending on the implementation of the container channels. The provider is the programmatic entity responsible for the generation of content, which is displayed in the channel. Generated content can consist of entire pages, frames, or channels; any markup.

As the amount of content on a portal increases, a containment method for referencing or referring to groups of content can facilitate the portal configuration, development, and end-user experience.The Sun ONE Portal Server provides a flexible, extensible set of container providers to aggregate content.

Figure 4-1 provides an example of the Desktop container hierarchy. In this figure, a Tab container is the top-level container. The Tab Container contains two Tab Channels, Tab 1 and Tab 2. Tab 2 is a Table Container and contains five channels.

Figure 4-1    Sample Desktop Container Hierarchy

Figure 4-1 illustrates the following containment types:

• Tab Container - Contains any number of table, single or tab containers. This container also includes contains the banners, and menu bars for the portal as well.
• Tab Channel - Aggregates the output of other channels, providing a tabbed user interface to switch between them. Tab containers configuration can be modified at runtime to vary which leaf channel is displayed.
• Table Container - Aggregates the content of other channels into rows and columns. This container functions much like the Sun™ Portal Server 3.0 front provider. It can be thought of as a bucket for the content of other channels.

Desktop Providers

Sun ONE Portal Server uses two types of providers:

• Building Block Providers—Extendable providers whose interfaces are public. These providers can be customized to meet specific customer requirements. These providers can generate more than one channel in the Desktop, thus the relationship between the provider and the channel is one to many.
• Content Providers—Non-extendable providers that provide content.These providers can have only a one-to-one relationship between provider and channel. These kind of providers are not building block providers.

The Desktop implements a display profile for storing content provider and channel data. See Chapter 5 "Administering the Display Profile," for more information.

Desktop Service

The Desktop is implemented through the Desktop service, which is part of the iPlanet Directory Server Access Management Edition framework. You use the iPlanet Directory Server Access Management Edition admin console to register the Desktop service for each organization or suborganization that you want to access a Desktop. You then create a display profile policy and assign it to users. You also use the iPlanet Directory Server Access Management Edition admin console to modify Desktop attributes. See Appendix C "Desktop Attributes," for more information.

Sample Desktops

Sun ONE Portal Server 6.0 provides a sample portal with five different Desktops. The sample Desktops enable you to install Sun ONE Portal Server and immediately see an example portal without having to develop one yourself.

Within the sample Desktops, Sun ONE Portal Server provides the following "out-of-the-box" channels:

• Bookmarks
• Applications
• User Information
• Search
• Notes
• Mail Check
• Login
• Simple Web Service
• Simple Web Service Configurable

These channels are not extendable, that is, Sun ONE Portal Server does not expose the APIs for these channels.

The sample Desktops are not intended for deployment, as they are generic in nature. You must customize Sun ONE Portal Server to your specific deployment needs.

Desktop Customization

When deploying Sun ONE Portal Server, one of your major tasks will be to develop, or customize your own portal. You will create and customize providers, channels and container channels, deploy your own online help, come up with a look-and-feel, and so on. If desired, you can use the sample Desktops as a starting point in customizing your site's portal. See the Sun ONE Portal Server 6.0 Desktop Customization Guide for more information on customizing your portal.

Overview of Hot Deployment of Channels

---

Sun ONE Portal Server enables you to deploy providers and channels on a live system without performing a restart, hence the "hot deployment." You can do so without interrupting user sessions.

The three technologies that facilitate hot deployment are:

• Provider class loader—Reloads providers and classes used by providers. For the provider class loader to function properly, all classes (or JAR files) must reside in a well-defined directory.
• Display profile refresh—Updates the in-memory Desktop configuration, that is, the display profile, if it has been changed by an external source such as the iPlanet Directory Server Access Management Edition admin console or the dpadmin command.
• Desktop Template and JSP reloading—Retrieves the appropriate template and JSP files for the Desktop type configured.

Overview of Provider Archives

---

The par utility enables you to package and transport channels and providers, and all associated files, in and out of the Sun ONE Portal Server system. The channel or provider is stored in the .par file format. Files included in the .par include:

• Display profile documents
• Class files
• "Property" based files, that is, JSP files
• Static content files, that is, HTML and image files

Administering the Desktop Service

---

The Desktop aggregates information in a user's display profile and displays the results to the user upon successful login. Display profiles can be defined at different levels in the iPlanet Directory Server Access Management Edition organization tree. Display profile documents from the various levels of the tree are merged or combined to create the user's display profile. For example, the user's display profile document is merged with the role display profile documents (if any), the organization's display profile document, and the global display profile document to form the user's display profile.

The Desktop display profile and other configuration data are defined as service attributes of the Desktop service under the iPlanet Directory Server Access Management Edition service management framework. When an organization registers for the Desktop service from the iPlanet Directory Server Access Management Edition admin console, all users within the organization inherit the Desktop service attributes in their user profiles. These attributes can then be queried by the Desktop servlet to determine how information will be aggregated and presented in the Desktop.

The following describes the high-level steps that you perform to configure the Desktop service for users in an iPlanet Directory Server Access Management Edition organization:

1. Enabling (registering) the Desktop service for a particular organization or suborganization.
2. Creating the Desktop service template.
3. Creating a Desktop policy and assign it to users.
4. Assigning a default redirect URL.
5. Customizing Desktop service attributes.




---

Note

If you install the sample portal, the installer installs all the necessary display profile XML files for the sample. You can customize the profiles using the iPlanet Directory Server Access Management Edition console or the command-line interface. See Chapter 5 "Administering the Display Profile," for further information.

---

To Register the Desktop Service

1. Log in to the iPlanet Directory Server Access Management Edition admin console as administrator.
2. Navigate to User Management by choosing View User Management.
3. Choose the organization for which you would like to register the Desktop service.
4. Choose Services from the Show menu.
5. Click Register in the navigation pane.

A list of available services displays in the data pane.

6. Select the check box for Desktop under Portal Server Configuration and click Register.

The Navigation pane is updated with the registered Desktop service under Portal Server Configuration.

To Create the Default Desktop Service Template

After registering the Desktop service, you can provide the default Desktop values to all users in an organization by creating a template for the Desktop service.

1. Log in to the iPlanet Directory Server Access Management Edition admin console as administrator.
2. Navigate to User Management by choosing View User Management.
3. Choose the organization for which you would like to create the default Desktop service template.
4. Choose Services from the Show menu.
5. Click the properties arrow next to Desktop in the navigation pane.
6. A question is displayed in a message box in the data pane to confirm if a service template should be created for the Desktop service. Click Create in the message box to create the template.
7. After the page is submitted and the template created, the data pane displays a list of Desktop service attributes and their default values, if any. Modify the values as needed. When done, click Save to store the final values in the service template.

The display profile of a newly created service template takes on the value entered in the Dynamic section of the Desktop service under Service Management. If those values were blank, the display profile in this new template is also blank.


---

Note	The default value for the Conflict Resolution Interval attribute is "Highest." Setting up service templates at different levels (for example, organization and role) with the same priority for a registered service could lead to unexpected results.

---

To Create and Assign a Desktop Policy to Users

After registering the Desktop service and creating a default service template, you enable all users in an organization to gain access to the Desktop service by creating a new policy and assigning it to users.

1. Log in to the iPlanet Directory Server Access Management Edition admin console as administrator.
2. Navigate to Policy Management by choosing View Policy Management.
3. Choose the organization for which you would like to create policy.

If you logged in as the Top Level Administrator, make sure that the location of the User Management interface is the top level organization where all configured organizations are visible. The default top level organization is o=isp.

4. Choose Policies from the Show menu.

By default, Organizations is visible in the Show menu. All sub-organizations configured, if any, will be visible below it. If creating the policy for a sub-organization, choose the sub-organization and then choose Policies from the Show menu.

A list of existing policies appears. Those that are assigned are indicated with a tilda (~).

5. Click New in the navigation pane.

Create Policy appears in the data pane.

6. Type the policy name and select Desktop from the Service menu.
7. Click Create to create the new policy.
8. Make sure Has Privilege to Execute Desktop is checked, set the appropriate Conflict Resolution Level, then click Save.
9. To assign the policy to users, navigate to User Management by choosing View User Management.
10. Choose the appropriate organization.
11. Choose Policies from the Show menu.

If the organization already has policies assigned to it, they are displayed in the Navigation pane. If the Assign Policies interface is not visible, click Assign and all unassigned policies will be displayed in the data pane.

12. Select the box next to the unassigned Desktop policy and click Assign to assign the policy to all users in the selected organization.

To Redirect Successful Login User to the Desktop URL

By default, users in an organization receive the Desktop service attributes and values after successfully logging in. These values can be queried by the Desktop servlet to determine the Desktop contents of any users in the organization. To instruct iPlanet Directory Server Access Management Edition to invoke the Desktop servlet automatically after a user has successfully logged in, you can change the value of the Default Redirect URL to the Desktop URL.

To set the default redirect for a specific organization to the Desktop URL:

1. Log in to the iPlanet Directory Server Access Management Edition admin console as administrator.
2. Navigate to User Management by choosing View User Management.
3. Select the organization for which you want to set the Desktop URL.
4. Choose Services from the Show menu.
5. Click the properties arrow next to Core in the navigation pane.
6. In the data pane, search for an attribute named User's Default Redirect URL.
7. Set the value of the User's Default Redirect URL to the URL for the Desktop servlet, for example, /portal/dt is the URL for the sample Desktop.
8. Click Save.
9. Verify the default redirect URL by logging in to the Desktop.

To Redirect Successful Login User to the Desktop URL (Global)

The values applied to the global attributes are applied across the iPlanet Directory Server Access Management Edition configuration and will be inherited by every newly created organization.

To set the Default Redirect URL to the Desktop URL globally:

1. Log in to the iPlanet Directory Server Access Management Edition admin console as administrator.
2. Navigate to Service Management by choosing View Service Management.
3. Click the properties arrow next to Core in the navigation pane.
4. In the data pane, search for an attribute named User's Default Redirect URL.
5. Set the value of the Default Redirect URL to the URL for the Desktop Servlet, for example, /portal/dt.
6. Click Save.

To Modify the Values of Desktop Service Attributes

You can customize the Desktop service by modifying its service attributes.

1. Log in to the iPlanet Directory Server Access Management Edition admin console as administrator.
2. Navigate to User Management by choosing View User Management.
3. Select the organization for which you want to modify the Desktop attributes.
4. Click the properties arrow next to Desktop in the navigation pane.

A list of Desktop service attributes, including the display profile XML, is displayed in the data pane.

5. Modify the service attribute values.

See "Desktop Dynamic Attributes" for information on the attributes.

6. When done, click Save.

The changes will affect only users in this particular suborganization or role.

To Modify the Values of Desktop Service Attributes (Global)

Occasionally, you need to modify the global Desktop service attribute values that affect all organizations that want to register for the Desktop service in the future.

The values applied to the global attributes are applied across the iPlanet Directory Server Access Management Edition configuration and are inherited by every configured organization.

1. Log in to the iPlanet Directory Server Access Management Edition admin console as administrator.
2. Navigate to Service Management by choosing View Service Management.
3. Click the properties arrow next to Desktop in the navigation pane.

A list of global Desktop service attributes, including the display profile XML, is displayed in the data pane.

4. Modify the service attribute values.

See "Desktop Global Attributes"" for information on the attributes.

5. When done, click Save.

The changes affect all organizations that register the Desktop service in the future.

To Log On to the Sample Desktop

1. Log out from the iPlanet Directory Server Access Management Edition admin console.
2. Log on with a user account (not the amadmin user) using the following URL:

http://server:port/portal/dt

If you need to create a user account, see "To Add a New User"."

To Examine the Desktop Logs

Desktop errors on the are logged to debug log files. By default, the location of these log files is as follows.

• /var/tmp/ipsdt.debug
• /var/opt/SUNWam/debug/desktop.debug
• /var/opt/SUNWam/debug/desktop.dpadmin.debug

Examine these log files for errors. An example follows. This error indicates that an unauthenticated user attempted to execute the desktop.

06/20/2002 02:36:30:600 PM PDT: Thread[Thread-177,5,main] ERROR: DesktopServlet.handleException() com.sun.portal.desktop.DesktopException: DesktopServlet.doGetPost(): no privilige to execute desktop at com.sun.portal.desktop.DesktopServlet.doGetPost(DesktopServlet.j ava:456) at com.sun.portal.desktop.DesktopServlet.service(DesktopServlet.jav a:303) at javax.servlet.http.HttpServlet.service(HttpServlet.java:853) at com.iplanet.server.http.servlet.NSServletRunner.invokeServletSer vice(NSServletRunner.java:897) at com.iplanet.server.http.servlet.WebApplication.service(WebApplic ation.java:1065) at com.iplanet.server.http.servlet.NSServletRunner.ServiceWebApp(NS ServletRunner.java:959)

Administering par Files

---

The par utility enables you to transfer or move providers or channels from one Sun ONE Portal Server to another. The par utility creates a specialized packaging mechanism called a .par file for transport of channels and providers into and out of the server. A .par file is an extended form of the .jar file format, with added manifest information to carry the deployment information and an XML document intended for integration into the Sun ONE Portal Server display profile on the target server.

The par command line utility is used to create, modify, and deploy par files. The export subcommand allows you to create or modify a par file. The import subcommand allows you to import or deploy the provider or channel on an Sun ONE Portal Server. See "par"" for detailed information on the syntax of the par command.

To use the par utility, you must be logged in as superuser to the Sun ONE Portal Server on which the files you want to export or import are resident. When you export you need to be sure to export all the required files for the channel or provider. For example, with channels you must include the static content files and with providers you must include all the class files used by the provider. Because specifying all the data to be included in the par file on the command line can be cumbersome, a simple text file with lines indicating the data can be created and this "export file" can called by the par utility. See "Export Files"" for further information.

To Create a New par File

To create a new par file to export a channel or provider:

1. Log in to the Sun ONE Portal Server from which to export the channel or provider.
2. Change directories to the directory where the script is installed. That is:

cd BaseDir/SUNWps/bin

3. At the command line, enter the par export command and subcommand and include the following arguments: the name of the par file to create, a directory server name argument corresponding to the desired display profile document to export, and any number of (requires at least one) export files or from specifications. For example, to export the channel mychannel from o=sesta.com,o=isp to the mychannel.par file, enter

./par export mychannel.par "o=sesta.com,o=isp" from: channel mychannel

See Chapter 12 "Command-Line Utilities" for syntax information.

To Modify an Existing par File

To modify an existing par file to export a channel or provider:

1. Log in to the Sun ONE Portal Server from which to export the channel or provider.
2. Change directories to the directory where the script is installed. That is:

cd BaseDir/SUNWps/bin

3. At the command line, par export command and subcommand with the modify option and include the following arguments: the name of the par file to modify, a directory server name argument corresponding to the desired display profile document to export, and any number of (requires at least one) export tiles or from specifications. For example, to modify the mychannel.par file to include the static content file /mycontent.html, enter

./par export --modify mychannel.par "o=sesta.com,o=isp" from= file /mycontent.html

To Deploy par Files

To import a par file to an Sun ONE Portal Server to deploy a provider or channel on the system:

1. Copy the par file for the provider or channel to import to the Sun ONE Portal Server on which to deploy the provider or channel.
1. Log in to the Sun ONE Portal Server on which to import the channel or provider.
2. Change directories to the directory where the script is installed. That is:

cd BaseDir/SUNWps/bin

3. At the command line, par import command and subcommand with the auto option and include the following arguments: the name of the par file to import, a directory server name argument corresponding to the desired display profile document to export, For example, to import the mychannel.par file, enter

./par import --auto myfile.par "o=sesta.com,o=isp"