|
| Sun ONE Portal Server 6.0 Deployment Guide |
Appendix D Sun ONE Portal Server Quick Start
This appendix provides the tasks you need to get started using Sun™ ONE Portal Server 6.0. This appendix covers installing and configuring the product, and creating adding channels to the Desktop, and creating custom providers.
This appendix contains the following sections:
- Locating Product Reference Information
- Installing Portal Server
- Configuring Portal Server (Post-Installation)
- Customizing the Desktop
- Creating Custom Providers
Locating Product Reference Information
You can interact with Portal Server as an administrator, developer, customizer, and user. At times, these distinctions might overlap. For example, as a developer, you might use both the Portal Server API and the Sun™ ONE Identity Server administration console to customize and configure the availability, content, and layout of the portal and its providers.
This section provides a set of references to assist you with the specific roles you fulfill in administering, customizing and developing Portal Server.
Installation Resources
The Sun ONE Portal Server 6.0 Installation Guide is available online at:
http://docs.sun.com/source/816-6358-10/index.html
Download the free trial version of the product at:
http://wwws.sun.com/software/download/products/sunone/3dee7b9e.html
Administration Resources
Information on understanding the Identity Server product and its administration console is available online at:
http://docs.sun.com/source/816-6359-10/dsameadm.html#23178
The Sun ONE Portal Server 6.0 Administrator's Guide is available online at:
http://docs.sun.com/source/816-6359-10/index.html
Customization Resources
The Sun ONE Portal Server 6.0 Desktop Customization Guide is available online at:
http://docs.sun.com/source/816-6361-10/index.html
Development Resources
The Sun ONE Portal Server 6.0 Developer's Guide is available online at:
http://docs.sun.com/source/816-6362-10/index.html
The Sun ONE Portal Server 6.0 Migration Guide is available online at:
http://docs.sun.com/source/816-6360-10/index.html
Installing Portal Server
This section provides an overview of and sample output from a Portal Server installation.
Portal Server Installation Tips
Note the following when installing Portal Server:
- You need to perform the installation as root.
- Before beginning the installation, check that no services are using ports 80, 8088 or 8900 (port 80 is used by Sun™ ONE Web Server, 8088 is used by the Web Server administration console, and port 8900 is used by the Sun™ ONE Directory Server administration console). You can change these ports if desired, but at a minimum, make sure that they are not already in use.
- If you are deploying on an application server, verify the server's port usage. For example, on the Sun ONE Application Server, the default administration console port is 4848. (7001 is the default for the BEA WebLogic console, and 900 is the default for the IBM WebSphere console.)
- Run ./pssetup in the directory where you unpacked the Portal Server installation file. See the Sun ONE Portal Server 6.0 Installation Guide for details.
Sample Portal Server Installation
The following sample installation shows the interaction with the Portal Server pssetup script. It creates an organization test the on host1 in the siroe.com domain and installs the sample portal.
Note This installation is for Portal Server with Sun™ ONE Web Server as the web application container. When installing an application server, the installation script is slightly different.
At this point the installation is complete, but Portal Server will not be started by the install. To start Portal Server, type:
/etc/init.d/amserver start
or
InstallDir/SUNWam/bin/amserver start
where InstallDir is the directory selected during installation. The default is the /opt directory.
To Verify That Portal Server Is Running
- In a browser, access the Identity Server administration console:
http://portalhost/amconsole
You must specify the Fully Qualified Domain Name (FQDN) of the Portal Server host, otherwise the login screen displays continually without authenticating. The login name is amadmin and the password is what you specified during installation as the passphrase.
To Change Font Size for the Administration Console
If you are using a Netscape browser that causes large fonts to be displayed in the Identity Server administration console, change the font size as follows:
- Log in to the Identity Server administration console as administrator.
- Select Service Management in the View drop-down menu.
- Click the Properties icon beside Client Detection in the navigation pane.
- In the Client Types box, click the line that begins with clientType=genericHTML.
- In the edit box below the list box, scroll to the right and replace UTF-8 with ISO-8859-1.
- Click Remove to delete the current genericHTML entry then click Add to add the new entry.
- Click Save.
- Log out of the administration console then log back in to see the smaller font size.
Configuring Portal Server (Post-Installation)
This section describes the most common configuration issues after installing Portal Server.
To Access the Anonymous Desktop Through the Portal Server Host Name (index.html File)
To access the Desktop login page using a URL in form http://psservername, you add some JavaScript™ code to the web server's index.html file in the /opt/SUNWam/public_html directory.
- Add the following JavaScript code to the index.html file. This example assumes that /portal/dt is the user's redirect URL.
<HTML>
<HEAD>
<SCRIPT>
document.location.href="/portal/dt?psdt.suid=uid=authlessanonymous,ou=
People,o=organization,o=isp" <-- for authless anonymous
</SCRIPT>
</HEAD>
</HTML>
Replace organization with your appropriate organization.
- Verify that you can now access the anonymous Desktop by typing the server name in the browser.
To Create a Sample Portal User
- Log in to the Identity Server administration console as administrator.
- By default, when you log in, User Management is selected in the View menu, and Organizations is selected in the Show menu.
- Navigate to the organization or suborganizaiton where the user will be created.
- Choose Users from the Show menu and click New.
The Create User template appears in the data pane.
- Type in the user information and click Create.
The new user appears in the navigation pane.
To Access the Desktop Attributes Page
- Log in to the Identity Server administration console as administrator.
- By default, when you log in, User Management is selected in the View menu, and Organizations is selected in the Show menu.
- Navigate to the organization for which you want to configure the Desktop.
- Choose Services from the Show menu.
- Click the Properties arrow beside Desktop.
The Desktop attributes page appears in the data pane.
To Configure a Non-tabbed Desktop
- Access the Desktop Attributes page.
If necessary, see "To Access the Desktop Attributes Page."
- Change the Default Channel Name attribute to JSPTableContainer.
- Click Save.
- Verify that the non-tabbed Desktop appears by logging out as the administrator and logging back in as a user.
If necessary, see "To Create a Sample Portal User."
To Configure a Tabbed Desktop
- Access the Desktop Attributes page.
If necessary, see "To Access the Desktop Attributes Page."
- Make sure that the Default Channel Name attribute is JSPTabContainer.
If necessary, make the change and click Save.
- Edit the tabbed Desktop display profile.
- Obtain the existing display profile profile by running the dpadmin command, for example:
This command outputs the display profile for the siroe organization to a file named /tmp/org.xml.
- Edit the three sample portal tabs as needed:
- MyFrontPageTabPanelContainer - Provides the "front page" tab
- SamplesTabPanelContainer - Contains sample channel providers
- SearchTabPanelContainer - Provides sample search functionality
For example, to change the captions of these tabs as seen on the Desktop, search the display profile output file for the relevant containers within the <TabProperties> and </TabProperties> tags and change the title property. To change channels, edit the channels within the <Selected> and <Available> tags.
- When done making changes, use the dpadmin command to re-insert this display profile back into the organization, for example:
The new display profile is active; there is no need to restart Portal Server.
- Verify that the modified Desktop appears by logging out as the administrator and logging back in as a user.
If necessary, see "To Create a Sample Portal User."
To Add a Tab to JSPTabContainer
A tab is represented by a table container. (A tab can be any container type but in general a table container is sufficient). To add a new tab, you must first define the container, then register that container in JSPTabContainer, which "houses" the tabs.
- Create the necessary display profile.
- Define the new collection within <Collection name="TabProperties"> in JSPTabContainer, for example:
...
<Collection name="TabProperties">
<Collection name="NewTabPanelContainer">
<String name="title" value="My Front Page"/>
<String name="desc" value="Your front page"/>
<Boolean name="removable" value="false"/>
<Boolean name="renamable" value="true"/>
<Boolean name="predefined" value="true"/>
</Collection>
...
</Collection>
...
- Add entries to the <Available> and <Selected> tags, for example:
...
<Available>
<Reference value="NewTabPanelContainer"/>
...
</Available>
...
<Selected>
<Reference value="NewTabPanelContainer"/>
...
</Selected>
...
- Define a container for NewTabPanelContainer, for example:
<Container name="NewTabPanelContainer" provider="JSPTableContainerProvider">
<Properties>
<String name="title" value="New Container Channel"/>
<String name="contentPage" value="tabtable.jsp"/>
<String name="description" value="This is a test for front table containers"/>
<String name="Desktop-fontFace1" value="Sans-serif"/>
<Collection name="categories">
<String value="Personal Channels"/>
<String value="Sample Channels"/>
</Collection>
<Collection name="Personal Channels">
<String value="UserInfo"/>
<String value="MailCheck"/>
</Collection>
<Collection name="Sample Channels">
<String value="SampleJSP"/>
<String value="SampleXML"/>
</Collection>
</Properties>
<Available>
<Reference value="UserInfo"/>
<Reference value="MailCheck"/>
<Reference value="SampleJSP"/>
<Reference value="SampleXML"/>
</Available>
<Selected>
<Reference value="UserInfo"/>
<Reference value="MailCheck"/>
<Reference value="SampleJSP"/>
<Reference value="SampleXML"/>
</Selected>
<Channels>
...
</Channels>
</Container>
- Load the display profile into LDAP by using the dpadmin command, for example:
- Verify that the modified Desktop appears by logging out as the administrator and logging back in as a user.
If necessary, see "To Create a Sample Portal User."
To Change the Channel Layout for a Table Container
You can configure a channel layout for each table container that houses channels for a tab (or JSPTableContainer for the channels in a non-tabbed desktop). To do this, edit the organization display profile XML and add the layout property to the table container.
- You can change the layout for a particular table container by modifying (or adding) the following property in the table container's display profile:
<Integer name="layout" value="value"/>
where value is:
1 = Thin-wide, two columns
2 = Wide-thin, two columns
3 = Thin-wide-thin, three columns
- Reload the display profile to LDAP by running the dpadmin command with the modify command, loading it at the top-most node in the directory by using the -g option.
To Deploy New Portal Content
- To make existing or new web content available from the Portal Server's web server, place the content under the /opt/SUNWam/public_html/ directory. If desired, you can change this directory to something more convenient.
Customizing the Desktop
This section covers a tasks for customizing the Portal Server Desktop.
To Configure the Desktop Banner
- Change to the appropriate container directory.
For example, for the JSPTabContainer,
cd /etc/opt/SUNWps/desktop/default/JSPTabContainer
For the anonymous Desktop banner (excluding the menu bar for Home, Options, Content, Layout, and so on), change to the /etc/opt/SUNWps/desktop/anonymous/JSPTabContainer directory. Change JSPTabContainer to JSPTableContainer if you are using the table-based Desktop.
- Edit the header.jsp file and modify the following line:
<td bgcolor="#333366"><img src="<dt:scontent/>/images/productName.jpg" width="274" height="38" alt="Sun ONE Portal Server"></td>
Replace <dt:scontent/>/images/productName.jpg with a reference to an alternate image.
For example, if you use /opt/SUNWam/public_html/images/newimage.gif, then use /images/newimage.gif as your replacement text. The <dt:scontent/> tag references image files from the Sun ONE Portal Server web application archive. Your own custom images need to be placed elsewhere, so the <dt:scontent/> tag is not used.
- Place your file in the appropriate directory.
You can place your custom image files under the web server document root, by default /opt/SUNWam/public_html, or you can deploy them in a custom web application archive. See the web server documentation for information on how to deploy a web application archive.
- Run the touch command on the container's top-level JSP file.
For example,
touch tab.jsp
- Reload the Desktop to verify the change.
To Add Channels and Container Channels to the Desktop
Portal Server uses channels to generate content for the Desktop. Generally, content is created by using JSP or template files. You configure channels by using properties, which affect the content, position on the Desktop, and channel controls. When you customize the value of properties that a channel receives, you customize that channel. (If you customize the value of properties for a provider, then all channels in the Desktop that use this provider are customized.)
Channels that contain other channels are called containers. Containers arrange channel content on the Desktop.
There are two methods you can use to add containers and channels to the Desktop:
- By using the Identity Server administration console (Edit Channels and Channel and Container Management links).
- By running the dpadmin command to upload an XML file with the necessary channel additions to the display profile into LDAP.
To add channels and containers by using the Identity Server administration console:
- Log in to the Identity Server administration console as administrator.
- Navigate to User Management by choosing View User Management.
- Select the organization, suborganization, or role to which you want to add a channel.
When you log in as a delegated administrator, you are automatically taken to the organization, suborganization, or role to which you have administrative access.
- Choose Services from the Show menu.
- Click the properties arrow next to Desktop in the navigation pane.
The Desktop attributes page appears in the data pane.
- In the Desktop page, click the Channel and Container Management link.
The Channels page appears, with the container path set at the root.
- Click the Container that you want to add the channel or container to.
Table D-1 explains a few of the containers. This is a two column-table. The first column lists the container and the second column provides a description.
After you make your selection, the top of the page displays the container path where the channel will be added. Defined channels and container, if any, appear in lists.
- Click Add to add a container channel or channel.
To add a container channel, click Add under Container Channel. To add a channel, click Add under Channel. The Add Channel page appears.
- Add the new channel to this container, make the channel available and visible on the Desktop, type a channel name, and select the type of provider from the menu. Table D-2 list the most useful providers. This is a two column table. The first column lists the provider name and the second column provides a description.
- Click Create.
You are returned to the Channels page. The added channel appears in Channels list.
- Click the Edit link next to the added channel.
The Edit Channel page appears.
- Make changes to the properties as needed then click Save.
- Verify that the added channel appears in the Desktop logging out as the administrator and logging back in as a user.
If necessary, see "To Create a Sample Portal User."
To Add a Custom Tab to the Desktop
- Log in to the portal as a user.
If necessary, see "To Create a Sample Portal User."
- Click the Tabs link at the top of the page.
The Current Tab Settings page appears.
- Click the Make a New Tab link.
The Make a New Tab page appears.
- Fill out the form and click Finished.
If you are making the tab from scratch, a page appears where you select the channels for the tab. Make your selections and click Finished.
- The Desktop appears with the new tab.
Creating Custom Providers
This section describes how to implement a custom provider. See the Sun ONE Portal Server 6.0 Developer's Guide for more information. Before starting, create a sample user as described in the section titled "To Create a Sample Portal User".
To Create a Custom Provider
- Choose the type of provider that you want to create.
You can choose between building block providers and content providers. For example, BookmarkProvider is a content provider, whereas an XMLProvider is a building block provider. There are three out-of-the box providers:
- JSPProvider - Uses JavaServer Pages™ technology to create the content for a channel on the Desktop.
- URLScraperProvider - Retrieves and displays content from a given URL.
- XMLProvider - Converts and displays an XML file according to the specified style sheet.
- Choose the presentation method.
There are three choices:
- The provider can get the content from JSP or template files.
- Channel template files are stored in a directory based on the name of the channel or the name of the provider that is used by the channel. The channel directory for the provider is created under the template root directory. By default, this is:
/etc/opt/SUNWps/desktop/desktoptype/channeldirectory/templatefiles
- Some of the JSP files are stored in the /etc/opt/SUNWps/desktop/default/provider directory and some are stored in the /etc/opt/SUNWps/desktop/default directory. Storing the files in the /etc/opt/SUNWps/desktop/default directory enables the files to be shared among multiple channels.
- Create a provider class file.
- You specify the provider deployment in the /etc/opt/SUNWps/desktopconfig.properties file. By default, the provider class base directory is /etc/opt/SUNWps/desktop/classes. For instant deployment, drop the JAR file in the directory specified in the providerClassBaseDir variable in the desktopconfig.properties file.
- Edit your source class.
For example, create the HelloWorldProvider class file as shown in Code Example D-2.
- Compile the class and put it in the user defined class directory.
javac -d /etc/opt/SUNWps/desktop/classes -classpath BaseDir/SUNWps/sdk/desktop/desktopsdk.jar:BaseDir/SUNWam/lib/servlet.jar HelloWorldProviderP.java
- Manually install the provider.
- Copy the file to provider class base directory, /etc/opt/SUNWps/desktop/classes. Or, copy the file to the location specified in the /etc/opt/SUNWps/desktop/desktopconfig.properties file.
- Create a provider definition file (for example, HelloChannelP.xml).
The sample HelloWorldProvider XML fragments for the provider in the HelloProviderP.xml and XML fragments for the channel in the HelloChannelP.xml files are shown in Code Example D-3 and Code Example D-4 respectively.
Code Example D-3 HelloProviderP.xml File
<Provider name="HelloWorldProviderP" class="custom.HelloWorldProviderP">
<Properties>
</Properties>
</Provider>
- Upload the provider and channel XML fragments using the dpadmin command.
For the sample HelloWorldProvider, upload the HelloProviderP.xml and HelloChannelP.xml XML fragments using the dpadmin command. That is, for example:
dpadmin add -u dn_amadmin -w password -d distinguishedname HelloProviderP.xml
dpadmin add -u dn_amadmin -w password -d distinguishedname HelloChannelP.xml
- Verify that the channel works. In a browser, type:
http://hostname:port/portal/dt?provider=HelloWorldP