Sun Java System Portal Server 6 2004Q2 Administration Guide |
Chapter 5
Administering the Portal Desktop ServiceThis chapter describes how to administer the Sun Java System Portal Server Desktop service.
This chapter contains these sections:
Overview of the DesktopThis section describes the Desktop component, its underlying structure, and how you administer it.
Desktop Glossary
Table 5-1 describes the pertinent Desktop terminology.
The first column of the table lists the term; the second column provides a definition of the term.
Portal Desktop Architecture and Container Hierarchy
The Desktop is the primary end-user interface for Sun Java System Portal Server. It is implemented through a servlet and is supported by various APIs and utilities (for example, Sun Java System 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 Java System Portal Server provides a flexible, extensible set of container providers to aggregate content.
Figure 5-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 5-1 Sample Portal Desktop Container Hierarchy
Figure 5-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 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 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 5-2 in the form presented.
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
Sun Java System Portal Server uses two types of providers:
- Building Block Providers—Extendable providers whose interfaces are public. These providers connects to a generic resource (like a JSP file). These providers can generate more than one channel in the Portal Desktop, thus the relationship between the provider and the channel is one to many.
- Content Providers—Non-extendable providers expects a specific set of data in order to render (for example, a bookmark provider expects a specific template and data). These kind of providers are not building block providers.
The Portal Desktop uses a display profile for storing content, provider, portlet, and channel data. See Chapter 7, "Administering the Display Profile" for more information.
Portal Desktop Service
The Desktop service uses Sun Java System 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 Java System Identity Server administration console to modify Desktop attributes. See Appendix C, "Portal Desktop Attributes" for more information.
Sample Desktops
Within the sample Desktops, Sun Java System 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 Java System 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 Java System Portal Server 6 2004Q2 Desktop Customization Guide for more information on customizing your portal.
Overview of Hot Deployment of ChannelsSun Java System 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 Sun Java System 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 ArchivesThe par utility enables you to package and transport channels, portlets, and providers, and all associated files, in and out of the Sun Java System 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 ServiceThe 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 Java System 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 Java System Identity Server service management framework. When an organization registers for the Portal Desktop service from the Sun Java System 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 Java System 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 Java System Identity Server console or the command-line interface. See Chapter 7, "Administering the Display Profile" for further information.
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 organization. The high-level steps to use policies are:
- 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.
- Log in to the Sun Java System Identity Server administration console as administrator.
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.
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.
- Log in to the Sun Java System Identity Server administration console as administrator.
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.
- Log in to the Sun Java System Identity Server administration console as administrator.
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 Java System 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:
- Log in to the Sun Java System Identity Server administration console as administrator.
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 Java System Identity Server configuration and will be inherited by every newly created organization.
To set the Default Redirect URL to the Portal Desktop URL globally:
- Log in to the Sun Java System Identity Server administration console as administrator.
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.
- Log in to the Sun Java System Identity Server administration console as administrator.
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 Java System Identity Server configuration and are inherited by every configured organization.
- Log in to the Sun Java System Identity Server administration console as administrator.
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
- Log out from the Sun Java System Identity Server administration console.
- 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 Chapter 3, "Administering Authentication, Users, and Services" for information.
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.
Administering PortletsPortlets are administered from the Sun Java System 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).
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.
To Create a Channel from a Portlet
- Log in to the Sun Java System Identity Server administration console and select your organization.
- 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,
- Select the Create button to create the portlet channel.
To Create a Channel from a Portlet for a Specific Container
- Log in to the Sun Java System Identity Server administration console and select your organization.
- 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:
- 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
- Log in to the Sun Java System Identity Server administration console and select your organization.
- 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
The portlet preferences are defined in portlet.xml
<portlet-preferences>
<preference>
<name>foo</name>
<value>apple</value>
</preference>
<preference>
<name>bar</name>
<value>orange</value>
<value>grape</value>
<read-only>true</read-only>
</preference>
</portlet-preferences>
is mapped to the following display profile:
<Collection name="__Portlet__AdditionalPreferences"/>
<Collection name="__Portlet__PreferenceProperties">
<Collection name="default">
<String name="foo" value="|apple"/>
<String name="bar" value="|orange|grape"/>
</Collection>
<Collection name="isReadOnly">
<Boolean name="foo" value="false"/>
<Boolean name="bar" value="true"/>
</Collection>
</Collection>
<String name="__Portlet__foo" value="|apple"/>
<String name="__Portlet__bar" value="|orange|grape"/>
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 "|".
- Log in to the Sun Java System Identity Server administration console and select your domain.
- 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 FilesThe par utility enables you to transfer or move providers or channels from one Sun Java System 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 Java System 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 Java System 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 Java System 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 5, "Administering the Portal Desktop Service" for further information.
To Create a New par File
To create a new par file to export a channel, portlet, or provider:
- Log in to the Sun Java System Portal Server from which to export the channel, portlet, or provider.
- 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 Appendix , "" for syntax information.
To Modify an Existing par File
To modify an existing par file to export a channel, portlet, or provider:
- Log in to the Sun Java System Portal Server from which to export the channel, portlet, or provider.
- 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 a Sun Java System 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 Java System Portal Server on which to deploy the provider or channel.
- Log in to the Sun Java System Portal Server on which to import the channel, portlet, or provider.
- 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"