Technical Note: Managing Sun Java System Portal Server 7.1 Update 1 Blog Portlet

Previous: Book Information

Blog Portlet

This technical note describes the steps to install and configure the Sun Java^TM System Portal Server Blog Portlet.

This technical note contain the following sections:

Technical Note Revision History

Version	Date	Description of Changes
10	03/07	First release of this technical note.

Overview of the Blog Portlet

Blog portlet allows portal users to manage weblog posts from a portal page. Users can create, edit, and delete weblog entries. Additionally, this portlet provides a simplified interface for creating weblogs and weblog user accounts.

Blog portlet is a client of an existing weblog server; it is not a weblog server, or service itself. Specifically, it requires Roller Weblogger version 3.1. The Portal Server software installer does not handle the Roller installation. See Installing Roller for more information.

Blog portlet utilizes the Atom Publishing Protocol (APP) for managing weblog posts. APP is the only standard protocol for weblog post management. In Roller, APP support is new and incomplete. Support for weblog servers other than Roller is not planned for this release of the Blog portlet.

Blog portlet also includes limited management of weblog server resources. It allows users to create weblog server user accounts and weblogs, utilizing the Atom Admin Publishing Protocol (AAPP).

This document is not a primer on weblogs, the APP and AAPP protocols, Roller, or Sun Java System Portal Server software. It is assumed that the reader understands these concepts and technologies.

Installing Roller

This technical note contain the following sections:

Roller Installation

Download Roller from the Roller project download page and refer to the Roller Weblogger project page for the detailed steps of installing and configuring Roller. Support files can be found at the Roller java.net support project download page. As part of Roller installation, you must configure a relational database and deploy a web application.

Once Roller is installed and running, enable the APP and AAPP web service endpoints. Refer to the Roller APP Installation / Configuration and AAPP Installation / Configuration wiki pages for details.

The default APP endpoint is:

http://<server>[:<port>]/roller/roller-services/app

The default AAPP endpoint is:

http://<server>[:<port>]/roller/roller-services/aapp

To test them, use the authget.sh, authpost.sh, authput.sh, and authdelete.sh scripts available from the Blogapps Examples java.net project page. These are simple command line utilities to do HTTP GET, POST, PUT, and DELETE operations with HTTP basic authentication. Since the APP and AAPP protocols are XML over HTTP web services that use the standard HTTP operations, you can fully interact with them in this manner.

Example 1 Validate APP Endpoint

To validate that the APP endpoint is enabled, do an HTTP GET on the endpoint URLs as shown below.

$ ./authget.sh roller-user-name roller-user-password http://siroe:8080/roller/roller-services/app
<?xml version="1.0" encoding="UTF-8"?>
<app:service xmlns:app="http://purl.org/atom/app#">
	<app:workspace>
		<atom:title xmlns:atom=http://www.w3.org/2005/atom">Jovial Junkyard</atom:title>
		<app:collection href="http://localhost:8080/roller/roller-services/app/
		 junkyard/entries">
			<atom:title xmlns:atom="http://www.w3.org/2005/atom">Weblog
			 Entries</atom:title>
			<app:categories app:fixed="yes" 
			 app:scheme="http://localhost:8080/roller/junkyard/">
				<atom:category xmlns:atom="http://www.w3.org/2005/atom" 
				 atom:term="/General" atom:label="General" />
				<atom:category xmlns:atom="http://www.w3.org/2005/atom" 
				 atom:term="/Status" atom:label="Status" />
				<atom:category xmlns:atom="http://www.w3.org/2005/atom" 
				 atom:term="/Java" atom:label="Java" />
				<atom:category xmlns:atom="http://www.w3.org/2005/atom" 
				 atom:term="/Music" atom:label="Music" />
				<atom:category xmlns:atom="http://www.w3.org/2005/atom" 
				 atom:term="/Politics" atom:label="Politics" />
			</app:categories>
			<app:accept>entry</app:accept>
		</app:collection>
		<app:collection href="http://localhost:8080/roller/roller-services/app/
		 junkyard/resources">
			<atom:title xmlns:atom="http://www.w3.org/2005/atom">Media Files</atom:title>
			<app:accept />
		</app:collection>
	</app:workspace>
</app:service>

Example 2 Validate AAPP Endpoint

To validate that the AAPP endpoint is enabled, do an HTTP GET on the endpoint URLs as shown below.

./authget.sh roller-admin-user roller-admin-pwd
 http://siroe:8080/roller/roller-services/aapp
<?xml version="1.0" encoding="UTF-8"?>
<service xmlns="http://purl.org/roller/aapp#">
	<workspace title="Workspace: Collections for administration">
		<collection title="Collection: Weblog administration entries" 
 	 href="http://localhost:8080/roller/roller-services/aapp/weblogs">
			<member-type>weblog</member-type>
		</collection>
		<collection title="Collection: User administration entries" 
 	 href="http://localhost:8080/roller/roller-services/aapp/users">
			<member-type>user</member-type>
		</collection>
		<collection title="Collection: Member administration entries" 
 	 href="http://localhost:8080/roller/roller-services/aapp/members">
			<member-type>member</member-type>
		</collection>
	</workspace>
</service>

Roller Deployment

Blog portlet creates Roller weblogs and users in a flat space. Such weblog server resources are not name-spaced by the Portal ID or any other identifier. The desired deployment is therefore one Roller server instance per portal

This image shows one Roller server instance per portal.

You can use a single Roller server instance for multiple portals.

This image shows one Roller server instance for multiple
portals.

In this situation, users in Portal A and B will not be allowed to have like-named weblogs. In a community context, users will not be able to have the community Blog service in like-named communities. This is because Blog portlet names the per-community weblog according to the community name.

Installing the Blog Portlet

The Portal Server software deploys the Blog portlet, but manual configuration is required because the Blog portlet requires a properly configured Roller server instance. Until the Roller server is running, Blog portlet cannot be used. Note that Java 1.4.x is the required Java version.

This technical note contain the following sections:

Configure the Portlet Preferences for the Blog Portlet

Depending on the desired use case (see Use Cases) for Blog portlet, some or all of the portlet preferences must be set. See Portlet Preferences for a description of the portlet preferences. These preferences can be configured at the provider or channel level.

To configure at:

The provider level, download the top level display profile, edit the XML directly, and then upload the display profile. Alternatively, create a display profile document that contains only the required changes and then run the psadmin modify-display-profile command with the --combine option to insert the modifications.

For example, to set the AAPP user name and password preferences:

$ cat blogportlet-provider.xml
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE DisplayProfile SYSTEM "jar://resources/psdp.dtd">
<DisplayProfile version="1.0" priority="0">
	<Properties/>
	<Channels/>
	<Providers>
		<Provider name="__Portlet__blogportlet.BlogPortlet"
		 class="com.sun.portal.providers.portletwindow.PortletWindowProvider">
			<Properties>
				<String name="__Portlet__aappUserName" value="|foo"/>
				<String name="__Portlet__aappUserPassword" value="|iplanet"/>
			</Properties>
		</Provider>
	</Providers>
</DisplayProfile>
$ /opt/SUNWportal/bin/psadmin modify-display-profile -u amadmin 
-f /tmp/pw -g -p portal1 --combine blogportlet-provider.xml

If you plan to configure the Blog community service, you must configure Blog portlet's preferences at the provider level.

The channel level, create a Blog portlet channel first. The preferences can then be edited from either the Portal Server management console or by using the psadmin command line utility.

Blog portlet can now be used outside of a community context. You can create channels based on this portlet using the psadmin command line utility or from the Portal Server management console.

Enable the Blog Community Service

This sections contains the following:

Overview of Community Service

When used in conjunction with Portal Server's Community Sample, Blog portlet provides for a per community weblog. Only community members can post to the weblog. If the Roller server user interface is left directly accessible, then all weblogs, including community weblogs, are visible to any user with access to the Roller server. Set up the Roller server in a headless configuration that only exposes the APP and AAPP endpoints. Refer to documentation in the Roller project page fore more information.

The Blog community service is not enabled by default (see Enabling Blog Community Service for more information on how to enable the Blog community service). When a new community is created that contains the Blog community service, Blog provisioning occurs.

Blog provisioning prepares a weblog for use within a newly created community. It performs the following steps automatically when a new community is created.

Creates community specific, shared weblog user account.
Creates a community specific weblog.
Adds the user account as a member of the weblog.
Sets various portlet preferences according to the weblog and weblog user account created in steps 1 and 2.

Note –

If the community specific weblog already exists, it is used as is. If the shared weblog user account already exists, it's properties are reset to those expected by the Blog community service.

The community weblog's handle (it's unique identifier) is equal to the community name. A weblog also has a description and various other properties. These are all set to generic default values when the weblog is created by provisioning. The values can be changed later by accessing the Roller server directly.

The APP entries URL, and the user name and password of the shared user, are set into the preferences of the community display profile. Therefore, all community users will get these preferences, and the community blog service will access the community weblog with the credentials of the shared user account. The author of new weblog posts will be the shared user.

If community users wish to access the weblog with a personalized (nonshared) weblog user account, they can do so by editing the Blog portlet. This allows the user to either create a new weblog user account or specify an existing one, and add the user to the community weblog as a member. Once the user personalizes their weblog user account settings, they cannot revert to the shared user account.

By default, when personalized by a community owner, the weblog user account is added as a member of the community weblog with the administrator role. When personalized by a community member, the user account is added with the author role. This behavior is controlled by the memberPermission portlet preference (see Portlet Preferences for more information).

If community users wish to customize the community weblog properties such as description and locale, they can do so by accessing the Roller weblog server directly. The default access URL for the Roller server is http://<server>[:<port>]/roller. The authenticating user must have the admin role in a weblog to modify weblog properties.

Portal community users can access the Roller weblog server directly (if it is configured to allow it). From there, they can post and otherwise manage the weblog entries of the Portal community weblogs (of which they are a member).

Enabling Blog Community Service

Make sure that Blog portlet's preferences in the display profile provider definition are correctly configured to talk to the Roller server. To test this, create a channel based on the Blog portlet. Without customizing the portlet channel's preferences, you must be able to use the channel to access weblogs on the server.

The portlet preferences you configure in Blog portlet's display profile provider definition will be used by the blog service in all communities. For example, the Roller AAPP URL and AAPP password will be used by the Blog community service in every community.

The Blog community service is not enabled by default. The process for doing so varies depending on whether the Portal Server 7.1 update 1 software instance is a new install or upgraded from Portal Server 7.1 software. To enable the Blog community service, ensure that the Blog community service is added to a community template.

For a New Install

For the community template with an ID of blogwiki, edit the community template role display profiles for the member (member.xml) and owner (owner.xml) roles and remove the XML comment blocks around the following Blog portlet elements.

The DP channel entry for the Blog channel in both member.xml and owner.xml files.
The community container's available and select channel lists in member.xml file.
The search service's availableDatabases property in member.xml file.

For an Upgraded Install

Add the Blog community service to the existing community templates.

Select a template in which to add the Blog community service and add the following Blog channel definition to the community template member role display profile. Override the default preference values as needed.

<Container name="%COMMUNITY_CONTAINER%" ...>
	...
	<Channel name="Blog" provider="__Portlet__blogportlet.BlogPortlet">
		<Properties>
			<String name="__Portlet__configMode" value="|wizard-user-only"/>

			<String name="__Portlet__memberPermission" value="|AUTHOR"/>
			<String name="__Portlet__searchUrl" value="|%COMMUNITY_SEARCH_URL%"/>
			<String name="__Portlet__searchDatabase" value="|
				%COMMUNITY_CONTENTS_SEARCH_DB%.blog"/>
		</Properties>
	</Channel>
	...
</Container>
...

Add the Blog channel to the community container's available and selected list.

...
<Container name="%COMMUNITY_CONTAINER%" ...>
	...
	<Available>
		<Reference value="%COMMUNITY_CONTAINER%/CommunityInfo"/>
		<Reference value="%COMMUNITY_CONTAINER%/Search"/>
		...
		<Reference value="%COMMUNITY_CONTAINER%/Blog"/>
		...
	</Available>
	<Selected>
		<Reference value="%COMMUNITY_CONTAINER%/CommunityInfo"/>
		<Reference value="%COMMUNITY_CONTAINER%/Search"/>
		...
		<Reference value="%COMMUNITY_CONTAINER%/Blog"/>
		...
	</Selected>
	...
</Container>
...

Add the Blog community service's search database to the search service's set of available search databases.

Note –

The value specified here must match the value specified in the searchDatabase preference in the channel definition.

...
<Container name="%COMMUNITY_CONTAINER%" ...>
	...
	<Channel name="Search" provider="SearchProvider">
		<Properties>
			...
			<Collection name="availableDatabases">
				<String name="%COMMUNITY_CONTENTS_SEARCH_DB%.blog" value="Blog"/>
			</Collection>
			...
	</Channel>
	...
</Container>
...

Add a channel definition to the owner role DP.

You can override the default portlet preference values in the community template role display profile Blog portlet channel definitions.
```
...
<Container name="%COMMUNITY_CONTAINER%" ...>
	...
	<Channel name="Blog" provider="__Portlet__blogportlet.BlogPortlet">
		<Properties>
			<String name="__Portlet__memberPermission" value="|ADMIN"/>
		</Properties>
	</Channel>
	...
</Container>
...
```
With these changes, newly created communities based on the modified template will contain the service. You must log out and log in to force the community templates to be reloaded.

Configuring the Blog Portlet

This sections contains the following:

Use Cases

The Blog portlet has the following use cases. These use cases are accomplished through a combination of the portlet's edit mode and the configMode portlet preference.

Admin configured

The portlet is configured by the portal administrator and can not be configured by the user. The admin configured mode expects that the portal administrator has configured the portlet for a group of portal users. For example, a portal administrator can add and configure the Blog portlet in an Access Manager role, giving all users with that role access to post to a shared weblog. No provisioning is performed. It is up to the portal administrator to ensure that the weblog server resources (weblog and weblog user account) exist.

This mode is configured by disabling the portlet's edit mode. If the portlet cannot be edited, the user cannot personalize the portlet in any way. By default, Blog portlet's deployment descriptor enables edit mode. To turn it off, set the value of the isEditableByMimeType property to false for Blog portlet's display profile provider.

For example:

$ cat blogportlet-noedit.xml
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE DisplayProfile SYSTEM "jar://resources/psdp.dtd">
<DisplayProfile version="1.0" priority="0">
	<Properties/>
	<Channels/>
	<Providers>
		<Provider name="__Portlet__blogportlet.BlogPortlet"
		 class="com.sun.portal.providers.portletwindow.PortletWindowProvider">
			<Properties>
				<Collection name="isEditableByMimeType" advanced="true">
					<Boolean name="text/html" value="false"/>
				</Collection>
			</Properties>
		</Provider>
	</Providers>
</DisplayProfile>
$ /opt/SUNWportal/bin/psadmin modify-display-profile -u amadmin -f /tmp/pw 
-g -p portal1 -m blogportlet-noedit.xml

All of the other configuration modes assume that the portlet is editable.

Manual configured

The portlet is configured directly by the user. The user can point to an existing weblog with an existing weblog account. No provisioning occurs. The manual configured mode allows the user to enter the weblog APP entries URL and their weblog user account credentials into a simple form. The user can personalize the Blog portlet to point to any weblog they wish.

This mode is configured is by making the portlet editable, and by setting the configMode preference (see Portlet Preferences) to manual.

Wizard configured

The portlet is configured by the user, walking them through a wizard to gather the various parameters. The weblog is provisioned based on the user's input. In wizard configured mode, when the user edits the portlet, they are walked through a series of questions and forms. The purpose is to allow them to choose an existing weblog user account or create one, and choose an existing weblog or create one. As opposed to the manual configuration mode, the wizard configured mode allows the user to enter a weblog handle only and not the weblog APP entries URL. The implication is that in wizard configured mode, users cannot vary the weblog server, only the weblog handle within the administrator configured weblog server.

This mode is configured by setting the configMode preference to wizard. This mode assumes that the portal administrator has configured valid APP and AAPP URLs into the portlet. Both are required. If not set, this mode will not be accessible and will default back to manual.

Wizard-user-only configured

The wizard-user-only configured mode is the same as wizard configured mode, but the user is only allowed to provision a weblog user, not a weblog. The wizard-user-only configured mode is the same as wizard configured mode, except that the weblog-related steps in the wizard are skipped; the user can only enter an existing weblog user account, or create a new one. They cannot change the weblog handle, or create a new weblog.

This mode is configured by setting the configMode preference to wizard-user-only. When used in conjunction with Portal Server software's community feature, Blog portlet must be set up in wizard-user-only configured mode.

Configuring Search

Weblog entries that are posted or modified by the Blog portlet are indexed into Portal Server's search server and Roller's embedded search engine (Lucene). Posts that are made or modified directly on the Roller server are not indexed into Portal Server's search engine; they are only indexed into Roller's embedded search engine. Portal Server's search server can be made to crawl the Roller server, but the indexes will not be protected and segregated per community. Search functionality can be disabled by resetting the searchUrl portlet preference. See Portlet Preferences for more information.

Configuring Security

This sections contains the following:

APP and AAPP Endpoints

Enabling the APP and AAPP endpoints in Roller should be carefully considered. Communication with these requires an unencrypted user name and password to be passed over the network (for HTTP basic authentication).

The AAPP endpoint allows removal or modification of any weblog or user account on the server. The APP endpoint allows removal or modification of any weblog entry or resource for which the authenticating user has access. If unencrypted credentials are a concern, consider running SSL on the Roller APP and AAPP endpoints.

Password Storage

APP and AAPP passwords are stored in Blog portlet's preferences. These passwords can either be stored in plain or DES 56-bit encrypted strings. If the portlet preference encryptedPasswords is set to true, then the portlet assumes that passwords are encrypted, otherwise it assumes plain passwords.

The default setting is plain passwords, encryptedPasswords=false. If encrypted passwords are enabled, the value for the APP user password is encrypted automatically as it is submitted by the user from the portlet's user interface. If passwords are entered directly, then they must be manually encrypted. Passwords can be entered directly by editing the portlet preferences in the Portal Server management console, or by editing the preferences in the community template role display profile.

To encrypt a plain password, use the supplied command line utility class: com.sun.portal.app.blog.password.Password. For example, to encrypt a password:

export CLASSPATH=WEB-INF/classes:WEB-INF/lib/commons-codec-1.3.jar
java com.sun.portal.app.blog.password.Password -c encrypt 
-k WEB-INF/classes/passwords.key -d '<plain password>'

Note –

If the path for the passwords.key file is set, navigate to the directory where the blog portlet is deployed (such as, /space/appserver/domains/domain1/applications/j2ee-modules/blogportlet if the application server is installed in /space), and then, run the java command.

The resulting string printed to standard out can be used as aappUserPassword and appUserPassword preference values.

Portlet Preferences

This section describes Blog portlet's portlet preferences.

appUrl: Set this to the APP endpoint of the Roller server instance. If not set, the portlet will assume manual configuration mode, regardless of the configMode preference value. To set this, specify the HTTP or HTTPS URL, or the empty string. By default, this is set to http://localhost:8080/roller/roller-services/app.
appEntriesUrl: Set this to the APP entries URL of the weblog that the portlet should manage. This preference can either be configured by the portal administrator for a group of users (per organization, per role), entered directly by the user (in manual configuration mode), or derived from the appUrl and handle preferences (in wizard configuration modes). Blog provisioning will set this preference to point to the community weblog. To set this, specify the HTTP or HTTPS URL. By default, this is set to http://localhost:8080/roller/roller-services/app/entries/junkyard.
appUserName: Set this to a Roller user name that has author privileges on the weblog pointed to by the preference appEntriesUrl. This preference can either be configured by the portal administrator for a group of users (per organization, per role), entered directly by the user (in manual configuration mode), or gathered from the user (in wizard configuration modes). Blog provisioning will set this preference to point to the shared weblog user account for the community. To set this, specify the Roller user name. By default, this is set to jtb.
appUserPassword: Set this to the password of the user account pointed to by the preference appUserName. This preference can either be configured by the portal administrator for a group of users (per organization, per role), entered directly by the user (in manual configuration mode), or gathered from the user (in wizard configuration modes). Blog provisioning will set this preference to the generated, random password of the shared community weblog user account. The password can be plain or encrypted depending on the value of the encryptedPasswords preference. To set this, specify the Roller user password. By default, this is set to iplanet.
aappUrl: Set this to the AAPP endpoint of a Roller server instance. If not set, the portlet will assume manual configuration mode regardless of the configMode preference value. To set this, specify the HTTP or HTTPS URL, or the empty string. By default, this is set to http://localhost:8080/roller/roller-services/aapp.
aappUserName: Set this to a Roller user account name that has the admin role in Roller. By default, this is set to jtb.
aappUserPassword: Set this to a password that matches the user account set in the aappUserName preference. The password should either be plain or encrypted depending on the value of the encryptedPasswords preference. To set this, specify the Roller user password for the user specified in the aappUserName preference. By default, this is set to iplanet.
handle: Set this to the weblog handle of the weblog pointed to by the appEntriesUrl preference. This preference is only relevant when the portlet is in wizard or wizard-user-only configuration mode. It can otherwise be left blank. To set this, specify the Roller weblog handle. By default, this is set to junkyard.
configMode: Set this according to the desired configuration mode. This preference is set to wizard-user-only mode in the community templates. Values can be manual, wizard, or wizard-user-only. For more information, see Use Cases. By default, this is set to manual.
memberPermission: Set this to the role that should be given when user accounts are added as members to weblogs in wizard or wizard-user-only configuration modes. This preference is set to ADMIN in the community templates for the owner, and AUTHOR in community templates of the members. Values can be ADMIN, AUTHOR, or VISITOR. By default, this is set to AUTHOR.
userUrl: Set this to the user access URL of a Roller server instance. This preference is used to give end users a link to the Roller server instance. To set this, specify the HTTP or HTTPS URL By default, this is set to http://localhost:8080/roller.
searchUrl: Set this the URL of a Portal search server instance. If not set, the portlet will not index weblog posts. In the community template, the value of this preference is a token that is replaced when the community is created. To set this, specify the HTTP or HTTPS URL. By default, this is set to http://localhost/search1/search.
searchDatabase: Set this to the name of the search database to use to index blog entries. In the community template, the value of this preference is a token that is replaced when the community is created. Values for this must be a string. By default, this is set to blog.
encryptedPassswords: Set this to true to assume encrypted password storage, or false for plain password storage. See Configuring Security for more information. To set this, specify the boolean value of true or false. By default, this is set to false.
pageSize: Set this to the number of weblog entries to display per page. The value is an integer and by default, this is set to 8.
refreshInterval: Set this to the number of seconds to delay weblog content refresh. A value of 0 refreshes weblog content on every page refresh. A value of -1 means never refresh. When the user modifies weblog content through the portlet (post, edit, delete), the content is refreshed regardless of the refresh interval. The value is an integer and by default, it is set to 1200.

Accessing Sun Resources Online

The docs.sun.com^SM web site enables you to access Sun technical documentation online. You can browse the docs.sun.com archive or search for a specific book title or subject. Books are available as online files in PDF and HTML formats. Both formats are readable by assistive technologies for users with disabilities.

To access the following Sun resources, go to http://www.sun.com:

Downloads of Sun products
Services and solutions
Support (including patches and updates)
Training
Research
Communities (for example, Sun Developer Network)

Third-Party Web Site References

Third-party URLs are referenced in this document and provide additional, related information.

Note –

Sun is not responsible for the availability of third-party web sites mentioned in this document. Sun does not endorse and is not responsible or liable for any content, advertising, products, or other materials that are available on or through such sites or resources. Sun will not be responsible or liable for any actual or alleged damage or loss caused or alleged to be caused by or in connection with use of or reliance on any such content, goods, or services that are available on or through such sites or resources.

Sun Welcomes Your Comments

Sun is interested in improving its documentation and welcomes your comments and suggestions. To share your comments, go to http://docs.sun.com and click Send Comments. In the online form, provide the full document title and part number. The part number is a 7-digit or 9-digit number that can be found on the book's title page or in the document's URL. For example, the part number of this book is 820-0041.

Previous: Book Information