Chapter 4 Administering the Portal Desktop Service

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

Overview of the Desktop

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

Desktop Glossary

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	Adapts the interface of a generic resource for use use by the Sun ONE Portal Server. A JSP provider compiles and executes a JSP file to generate a markup. An XML provider translates an XML file to generate a markup The portal server can also query the provider for information to display a markup on a portal page.
Portlet	Pluggable web components that process requests and generate content within the context of a portal. Portlets are managed by the Portlet Container (an implementation of the Portlet Specification as defined by the JSR168 Expert Group). Conceptually they are equivalent to the software Providers.
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).

Portal 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, Sun™ ONE Identity Server 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.

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 are 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.

User Defined Channels

Each tab in a tab container includes a Content link. If you select the Content link, a page where a user can select the channels they would like to appear in the current tab’s container is displayed. In this release, an additional link on the top right of this page, Create New Channel link, is included. The Create New Channel link, when selected, presents a page where a user can create a new channel. However, the channels that can created by the user is definable by the administrator.

To create a new channel (from the page shown in ), the user must specify the information outlined in Table 4-2 in the form presented.

Table 4-2 User Defined Channels
Form Field	Field Type	Field Description
Channel Name	Text field	Channel name may contain only letters (a-z,A-Z) and digits (0-9).
Channel Title	Text field	This is the title that will appear in the Channel titlebar.
Channel Description	Text field	This is the description for the Channel that appears on the Content link page.
Channel Type	Combo box	This is a list of Providers that new Channels can be created from.
Channel Category	Combo box	This is a list of the Categories for the Tab’s Container.
Display Channel	Radio buttons with "Yes" and "No"	Select Yes for Display Channel so that the new Channel will automatically be displayed when the Browser is refreshed after selecting the Create button. Select No so that the Channel will not automatically be displayed when the Browser is refreshed after selecting the Create button. Instead, the channel can be displayed in the Browser by selecting the Channel from the Content link. In either case, once the new Channel is selected and displayed in the Browser, it is necessary to update its properties by selecting the Edit button which is available in the newly created Channel’s titlebar.
Create	Button	Select Create to create the new Channel.
Cancel	Button	Select Cancel to return the user to their Desktop display.

The Delete A Channel link is displayed on the Content page after a user has created a user-defined channel. When a user clicks on the link, a list of all of the channels that the user created is displayed for possible deletion.

Portal Desktop Providers

Portal Desktop Service

The Desktop service uses Sun ONE Identity Server services to store application and user-specific attributes for each organization or suborganization. You then create a display profile policy and assign it to users. You also use the Sun ONE Identity Server Sun ONE Identity Server administration console to modify Desktop attributes. See Appendix C, "Portal Desktop Attributes" for more information.

Sample Desktops

Within the sample Desktops, Sun ONE Portal Server includes the following channels:

These channels are customized and configured for the sample portal. They may require the modification of the user interface before they are deployed.

Portal 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 create and extend 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.1 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.

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 Sun ONE Identity Server Sun ONE Identity Server administration console or the dpadmin command.

Portal 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, portlets, and providers, and all associated files, in and out of the Sun ONE Portal Server system. The channel, portlet, or provider is stored in the .par file format. Files included in the .par include:

Administering the Portal Desktop Service

The Desktop merges all of the documents in a user’s display profile merger set and uses the result to configure the user’s desktop. A display profile merger set consists of all the display profile documents associated with a user. Display profiles are defined at different levels in the Sun ONE Identity Server 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 Portal Desktop service under the Sun ONE Identity Server service management framework. When an organization registers for the Portal Desktop service from the Sun ONE Identity Server administration console, all users within the organization inherit the Portal Desktop service attributes in their user profiles. These attributes are queried by the Portal Desktop to determine how information will be aggregated and presented in the Portal Desktop.

By default, the Policy Configuration service is automatically registered to the top-level organization. Suborganizations must register their policy services independently of their parent organization. Any policy service you create must be registered to all organizations.

The following describes the high-level steps that you perform to configure the Portal Desktop service for users in an Sun ONE Identity Server organization:

Registering the Policy service for an organization.

Creating a referral policy for a peer or suborganization.

Creating a normal policy for a peer or suborganization.

Assigning a default redirect URL.

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 Sun ONE Identity Server console or the command-line interface. See Chapter 5, "Administering the Display Profile" for further information.

Registering the Policy service for an organization. (This will be done automatically for the organization specified at installation.) Suborganizations do not inherit their parent’s services, so you need to register a suborganization’s Policy service. See To Register a Policy Service for a Suborganization for information.

Creating a referral policy for a peer or suborganization. You can delegate an organization’s policy definitions and decisions to another organization. (Alternately, policy decisions for a resource are delegated to other policy products.) A referral policy controls this policy delegation for both policy creation and evaluation. It consists of a rule and the referral itself. If the policy service contains actions that do not require resources, referral policies cannot be created for suborganizations. See To Create a Referral Policy for a Suborganization for information.

Creating a normal policy for a peer or suborganization. You create a normal policy to define access permissions. A normal policy can consist of multiple rules, subjects, and conditions. See To Create a Normal Policy for a Suborganization for information.

To Register a Policy Service for a Suborganization

Suborganizations do not inherit their parent’s services, so you need to register a suborganization’s Policy service.

By default, Identity Management is selected in the location pane and All created organizations are displayed in the navigation pane.

Choose the organization for which you would like to register the Desktop service.

Choose Services from the View menu in the navigation pane.

Click Register in the navigation pane.

A list of available services displays in the data pane.

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

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

Choose Services from the View menu in the navigation pane.

Click the properties arrow next to Desktop in the navigation pane.

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.

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 Portal 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 a Referral Policy for a Suborganization

You can delegate an organization’s policy definitions and decisions to another organization. A referral policy controls this policy delegation for both policy creation and evaluation. It consists of a rule and the referral itself. The referral must define the parent organization as the resource in the rule, and it must contain a SubOrgReferral with the name of the organization as the value in the referral.

By default, Identity Management is selected in the location pane and All created organizations are displayed in the navigation pane.

Select Identity Management from the navigation pane.

Select Policies from the View menu.

Click New to create new policy.

The Create Policy page appears in the data pane.

For Name, type SubOrgReferral_Desktop. Make sure you select Referral in Type of Policy. Then click Create.

Select Desktop in Service and click Next

Click Rules from the View menu in the data pane and click New. Make sure Portal Desktop is selected and click Next.

The New Rule template appears in the data pane.

Enter DesktopRule in Rule Name and click Create.

Click Referrals from the View menu in the data pane and click New.

The New Referral template appears in the data pane.

Enter SubOrgReferral_Desktop in Name.

Make sure that the name of the suborganization is selected for Value in the data pane and click Create to complete the policy’s configuration.

Click Save in the data pane.

The message “The policy properties have been saved” is displayed when the data is saved.

To Create a Normal Policy for a Suborganization

You create a normal policy to define access permissions. A normal policy can consist of multiple rules, subjects, and conditions.

By default, Identity Management is selected in the location pane and All created organizations are displayed in the navigation pane.

Navigate to the organization or suborganization that you want to assign a policy.

All created organizations are displayed in the navigation pane.

Choose Policies from the View menu.

The policies for that organization are displayed.

Select New in the navigation pane. The New Policy page opens in the data pane.

Enter SubOrgNormal_Desktop in Name. Make sure you select Normal in Type of Policy. Click Create

Choose Rules from the View menu in the data pane and click New. The New Rule page opens in the data pane

Select Portal Desktop from the Service menu and click Next. Enter DesktopRule in Rule Name. Make sure Has Privilege to Execute NetMail is checked

Select Portal Desktop from the Service menu and click Next. Make sure Has Privilege to Execute NetMail is checked.

Select the type of subject from the Type menu and click Next to complete subject configuration.

Choose Subjects from the View menu in the data pane and click New. The New Subject page opens in the data pane.

Click Create to complete the policy configuration.

The message “The policy properties have been saved.” is displayed when the data is saved.

To Redirect Successful Login User to the Portal Desktop URL

By default, users in an organization receive the Desktop service attributes and values after successfully logging in. These values are queried by the Desktop servlet to determine the Portal Desktop contents of any users in the organization. To instruct Sun ONE Identity Server to invoke the Portal Desktop servlet automatically after a user has successfully logged in, you can change the value of the Default Redirect URL to the Portal Desktop URL.

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

By default, Identity Management is selected in the location pane and All created organizations are displayed in the navigation pane.

Select the organization for which you want to set the Portal Desktop URL.

Choose Services from the View menu.

Click the properties arrow next to Core in the navigation pane.

In the data pane, search for an attribute named User’s Default Redirect URL.

Set the value of the User’s Default Redirect URL to the URL for the Portal Desktop servlet, for example, /portal/dt is the URL for the sample Desktop.

Click Save.

Verify the default redirect URL by logging in to the Portal Desktop.

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

The values applied to the global attributes are applied across the Sun ONE Identity Server configuration and will be inherited by every newly created organization.

By default, Identity Management is selected in the location pane and All created organizations are displayed in the navigation pane.

Choose Service Management in the location pane.

Click the properties arrow next to Core in the navigation pane.

In the data pane, search for an attribute named User’s Default Redirect URL.

Set the value of the Default Redirect URL to the URL for the Portal Desktop Servlet, for example, /portal/dt.

Click Save.

To Modify the Values of Portal Desktop Service Attributes

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

By default, Identity Management is selected in the location pane and All created organizations are displayed in the navigation pane.

Select the organization for which you want to modify the Desktop attributes.

Click the properties arrow next to Desktop in the navigation pane.

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

Modify the service attribute values.

See Appendix C, "Portal Desktop Attributes" for information on the attributes.

When done, click Save.

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

To Modify the Values of Portal 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 Sun ONE Identity Server configuration and are inherited by every configured organization.

By default, Identity Management is selected in the location pane and All created organizations are displayed in the navigation pane.

Choose Service Management in the location pane.

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.

Modify the service attribute values.

See Appendix C, "Portal Desktop Attributes" for information on the attributes.

When done, click Save.

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

To Access the Sample Portal Desktop

To Examine the Desktop Logs

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

Examine these log files for errors. An example follows. This error indicates that an unauthenticated user attempted to execute the Portal 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.sun.server.http.servlet.NSServletRunner.invokeServletService (NSServletRunner.java:897)

at com.sun.server.http.servlet.WebApplication.service(WebApplicatio n.java:1065)

at com.sun.server.http.servlet.NSServletRunner.ServiceWebApp(NSServ letRunner.java:959)

Administering Portlets

Portlets are administered from the Sun™ ONE Identity Server administration console. The administration console includes pages for creating portlet channels from portlets and changing preferences of portlet channels. The pdeploy is a command line tool that can be used to deploy and undeploy the portlet web application into a web container (see Command-Line Utilities for more information).

To Create a Channel from a Portlet


Note	If a client request accesses a portal page which contains at least one session-enabled portlet, it is strongly recommended that all the portlets on that portal page should be packaged within a single portlet application, otherwise the resulting behavior of the session creation may be nondeterministic."

Select Services under Show in the navigation menu.

Select the Desktop service from Portal Server Configuration.

Select Channel and Container Management link.

Select the Add Portlet Channel button under Channels.

The page to create a portlet channel is displayed.

Specify in the Add Channel page,

The channel name.

Note that channel names can contain only letters (A through Z) and digits (0 through 9) and it is a required field.

The Portlet

Only contains portlets that are deployed in the system are displayed.

Select the Create button to create the portlet channel.

Figure 4-2 Add Portlet Channel Page Sample

To Create a Channel from a Portlet for a Specific Container

Select Services under Show in the navigation menu.

Select the Desktop service under Portal Server Configuration.

Select Channel and Container Management.

Select the link to the Container where you wish to create a portlet channel.

The page for managing the container is displayed.

Select the Add Portlet Channel button under Channels.

The page for creating and adding a portlet channel is displayed. .

Specify, in the Add Channel page:

A name for the channel.

The Portlet from the pull-down list. The list only contains portlets that are deployed in the system.

Whether the channel will be available to end-users or whether it will be available and visible on the Desktop by selecting the appropriate radio button.

Select the OK button.

Note that the channel is added to the list of channels under Channels and under Available and Visible in the Container Management page.

To Add the Portlet Channel to a Container

Select Services under Show in the navigation pane.

Select Desktop from Portal Server Configuration.

Select Channel and Container Management.

Select the link to the Container to which you wish to add the newly created portlet channel.

The page for managing the container is displayed.

Select the portlet channel you wish to add Channel Management and select Add.

This will add the selected portlet channel to the list of channels available and visible on the selected container.

Select Save button under Channel Management to save the new settings.

To Edit a Portlet Channel Preferences and Properties

There is an empty collection __Portlet__AdditionalPreferences created to hold the preferences added during runtime. The collection __Portlet__PreferenceProperties contains two collections, default and isReadOnly. The default collection stores the default values as defined in portlet.xml. Similar to the default collection, the isReadOnly collection stores the read-only flags of the preferences using Boolean properties.

Each preference in the portlet.xml has one corresponding String property in the default collection with the preference name as the property name. The value of the String property is to represent the default value defined in portlet.xml prepended and delimited by the character "|". Each preference is then represented by a String property which stores the current value of the preference. The name of the property is the name of the preference prepended by the string __Portlet__. The value of the property is the current preference values prepended and delimited by the character "|".

Select Services under Show in the navigation pane.

Select Desktop from Portal Server Configuration.

Select Edit link for the portlet channel you wish to edit.

The Edit Channel page is displayed. The channel edit page displays the portlet preferences for the portlet entity.

Modify the preferences and select Save to save the modifications.

To modify the default values of the preferences, select Edit link for the preference you wish to edit. Properties can be edited in the Edit Channel page.

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, portlets, 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, channel, or portlet on an Sun ONE Portal Server. The describe subcommand describes the contents of a par file. 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, portlet, 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 is created and this “export file” is called by the par utility. See Chapter 4, "Administering the Portal Desktop Service" for further information.

To Create a New par File

Change directories to the directory where the script is installed. That is:

cd BaseDir/SUNWps/bin

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 14, "Command-Line Utilities" for syntax information.

To Modify an Existing par File

Change directories to the directory where the script is installed. That is:

cd BaseDir/SUNWps/bin

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 "dc=sesta,dc=com" “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:

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.

Change directories to the directory where the script is installed. That is:

cd BaseDir/SUNWps/bin

At the command line, par import command and subcommand 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 "do=sesta,dc=com"