Sun Java System Portal Server 7.2 Administration Guide

Chapter 9 Managing a Portal Server Community

This chapter describes the management of a community and its users. This functionality is made available to a community owner through the Community Info portlet. Similar functionality is made available to system administrator through the Portal Server management console and psadmin command line interface. Refer to the Technical Note: Managing Sun Java System Portal Server 7.2 Update 1 Communities Technical Note for information on the command line utilities for managing communities.

Note –

If you need to set Community Attributes to your portal, follow the procedure described in the procedure To Add the Community Sample in the link, http://docsview.sfbay/app/docs/doc/820-0043/gdsbd?1=en&a=view.

This chapter has the following sections:

Understanding Portal Server Communities

This chapter contains the following:

Managing Access Control

While the concept of “community” has a general notion of being publicly open and making information accessible to everyone, there is a great need for establishing access control around the communities. As in the case of enterprise-based communities, the audience of certain communities might need to be restricted and the data posted to these communities be kept private and secure. This section describes the available access control settings and the common configurations for them.

Available Settings

Following are the three community aspects on which access controls can be set based on requirement of a community.

Membership Access

Unrestricted Membership (Public): A community with an unrestricted membership is open for anyone to join.
Restricted Membership (Private): A community with a restricted membership requires a user to make a request (to the owner of the community) and be granted or denied of the membership. Alternatively, the owner can invite or explicitly add one or more users to the community.

Community Listing

Listed (Public): A community is registered in the community categories and can be browsed and searched by anyone.
Unlisted (Private): A community cannot be searched and is not browsed in the community categories.

Secured Content

Unsecured (Public): The data posted on the community has the potential of being searched and accessed by non-members.
Secured (Private): All data posted on the community will be strictly protected and can only be searched and accessed by the members.

Common Configurations

A community owner or a system administrator can control the various aspects of the access control during or after creation of the community. Note that each setting described in the Available Settings section is independent of each other. In other words, selecting one option for a setting will not influence the behavior or selection of the other settings. For instance, a community with (unrestricted) membership can be unlisted or its content can be made secured. Owner of a community can customize the access control based on the nature of the community. The two most common configurations are explained here.

Public Community

A public community is open for anyone to join and gain membership. The community is listed in the community categories and can be browsed and searched by anyone. The content posted on community is also searchable and accessible to anyone.

Communities created on previous release of Portal Server software are considered public communities and will operate like a public community when the system is upgraded to this release of the Portal Server software.

Private Community

A private community is the most secure form of a community. It is hidden from the community categories thus cannot be browsed nor searched. Private community is a community that is unlisted, secure, and having restricted membership. The community owner can invite or manually add users to the community. The content of the community is protected from non-members such that they will not be able to view or search any posted content.

Managing Membership

A user can be assigned different roles in a community. The two primary roles are OWNER and MEMBER. A user in MEMBER role has all the regular member privileges. If it is assigned the OWNER role too, it will assume additional privileges to manage the community. The privileges and the content presented to the user are controlled by the merge of the corresponding display profiles for each of the role assigned to a user. System administrator must be careful when designing the display profiles templates for each community role. Please see the community template chapter for more details.

A non-member user implicitly assumes the VISITOR role and as a result, the visitor.xml is always merged when a non-member user visits a particular community page. A user is referred as a non-member when it either has no explicit role or has transient roles like BANNED, INVITED, PENDING and REJECTED.

Restricted Membership Workflow

In order for a user to join a community which is either private or has a restricted membership, a membership request should be made by the interested user. The owner of the community then either approves or denies the request. When approved, the user immediately becomes a member of the community. On the other hand, a denied user receives notice of rejection when the user logs into the portal and upon acknowledging the rejection, the user returns to the visitor status. A denied user can then submit request again at a later time. Owners can ban certain users if the owner does not even want the users to submit a request for membership.

VISITOR	--request membership-->	PENDING/VISITOR-->	approved-->	MEMBER
VISITOR	--request membership-->	PENDING/VISITOR-->	denied
																							|
																	-->REJECTED/VISITOR	--acknowledges-->	VISITOR

Inviting Users

As an owner of a community, one can send invitation to users to join the community. An invited user can see the invitation when the user logs into portal. The user then has an option to either accept or decline the invitation.

VISITOR-->		invited-->	INVITED/VISITOR-->	accepts-->	MEMBER
VISITOR-->		invited-->	INVITED/VISITOR-->	declines-->	VISITOR

When the system is set up properly, an invitation message is sent to the invited users through email. In order to receive an invitation through email, the user must have email address properly configured in their portal.

Banning Users

Banning is a process by which the owner can prohibit certain users from accessing the community. Both members and non-members, as well as owners, can be banned from the community and in the case of a restricted membership community, a banned user cannot even submit a request to join the community.

A banned user can be unbanned by the owner and the user's prior privileges are reinstated. If the user was a member before getting banned, the user becomes a member after getting unbanned. Likewise, when an owner gets banned from a community and is then unbanned, the owner becomes the owner of the community again.

MEMBER-->				banned-->	BANNED/VISITOR-->		unbanned-->	MEMBER
OWNER/MEMBER-->		banned-->	BANNED/VISITOR-->		unbanned-->	OWNER/MEMBER

Managing a community status

This section contains the following:

Enabling and Disabling a Community

A portal administrator, using either Portal Server management console or psadmin CLI, can disable a community. Likewise, only the portal administrator can enable a disabled community. Access to a disabled community is blocked to everyone including members and owners. An attempt to search for any content posted on a disabled community would yield no result. By default, a newly created community is enabled.

Use disabled.xml template to show how a disabled community would be presented to users. See Understanding Community Templatesto understand the display profiles for a community template.

Deleting and Restoring a community

A community owner or a system administrator can delete a community. When a community is deleted, the community itself and the data pertaining to the community are not accessible. However, in the back-end storage, the data still remains and thus the community can be restored on demand. The task of restoring a deleted community is done by the portal administrator. This undo functionality is made available to reverse a malicious or accidental deletion of a community. Since the deletion is not permanent, a new community by the same name can not be created. A permanent and persistent removal of a community is currently not supported. But we can use psadmin subcommand destroy-community to remove the community permanently.

Use deleted.xml template to show how a deleted community would be presented to users. See Understanding Community Templates to understand the display profiles for a community template.

Managing Categories

The category tree used in creating communities as well as browsing communities is provided by the taxonomy of the search server. To manage them, please see Managing Categories.

Understanding Community Templates

This chapter contains the following:

Overview of the Community Template

This section contains the following:

What Is A Community Template?

A community template is comprised of a set of services (channels) and the visual layout. However, the layout is not always dictated by the community template as in the case with wiki community template where the layout is dictated by the wiki itself. Community templates define (in the role display profile document) the type of services available for the community, the default settings for each service, and the containers that bind the services.

Physically, a community template is a properties file, and image, plus one or more display profile documents. There are display profile documents, one per community role (such as OWNER, VISITOR, MEMBER). Each role template defines services and the layout associated with the particular role (see Managing Membership for more information on these roles). The content of the role template is represented in a display profile document. In essence, a community template contains the logic for handling different roles (one display profile document per role) and depending on the one or more roles, you get a different set of services and a different layout. There are also display profile documents to customize the content when communities are marked for deletion (deleted.xml) or disabled (disable.xml).

Communities are created from a community template. The system may have any number of community templates. In the Enterprise Sample, end users choose a community template when they create a community.

How Are The Templates Stored?

The community templates are stored on filesystem. Community templates are stored in PortalServer-DataDir/portals/portal-URI/communitytemplates directory (referred to as communityTemplateBaseDir). Note that this means that each Portal (in a multi-portal deployment environment) will and must have its own set of community templates. The resource bundle in communityTemplateBaseDir defines the meta data associated with each template. In addition, each template has its own directory where the role templates are stored.

Example 9–1 Sample `communityTemplateBaseDir`

communityTemplateBaseDir   -+-- template1 -+-- deleted.xml
                            |              |
                            |              +-- disabled.xml
                            |              |
                            |              +-- member.xml
                            |              |
                            |              +-- owner.xml
                            |              |
                            |              +-- visitor.xml
                            |
                           -+-- template2 -+-- deleted.xml
                            |              |
                            |              +-- disabled.xml
                            |              |
                            |              +-- member.xml
                            |              |
                            |              +-- owner.xml
                            |              |
                            |              +-- visitor.xml
                            |
                           -+-- template3 -+-- deleted.xml
                            |              |
                            |              +-- disabled.xml
                            |              |
                            |              +-- member.xml
                            |              |
                            |              +-- owner.xml
                            |              |
                            |              +-- visitor.xml
                            |
                            +-- template1.properties
                            |
                            +-- template1_en.properties
                            |
                            +-- template1_fr.properties
                            |
                            +-- template2.properties
                            |
                            +-- template3.properties
                            |
                            +-- template3_en_US.properties
                            |
                            +--       ...

The display profile disabled.xml and deleted.xml files control the content when the community is disabled or marked for deletion. See Managing a community status for more information.

How Are The Templates Managed?

The portal administrator can add a new community template, update an existing community template, archive and restore community templates on the system, and export community templates from one portal instance to others and/or keep them in sync.

Template Syntax and Semantics

Each template is made up of one or more role templates (member.xml, owner.xml, visitor.xml, deleted.xml, disabled.xml) in XML format. The template directory includes the XML files for the roles that it will serve; for example, member.xml for the community member, owner.xml for the community owner, and visitor.xml for the community visitor.

Each role template is a display profile document for community users in that role. The file must be based on the display profile DTD.

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE DisplayProfile SYSTEM "jar://resources/psdp.dtd">
<DisplayProfile version="1.0" priority="%COMMUNITY_DP_PRIORITY%">
	<Properties/>
	<Channels>
		<Container name="%COMMUNITY_CONTAINER%" provider="JSPTableContainerProvider">
			<Properties>
				<String name="title" value="%COMMUNITY_NAME%"/>
				<String name="description" value="%COMMUNITY_DESCRIPTION%"/>
				<Boolean name="compileToRealPath" value="true"/>
			</Properties>
			<Available>...</Available>
			<Selected>...</Selected>
			<Channels>...</Channels>
	</channels>
	<Providers/>
</DisplayProfile>

The tokens (surrounded by %), described below, in the display profile are dynamically replaced by actual values by the template engine when a community is created.

%COMMUNITY_NAME%: Specifies the (user-friendly) name given to the community. For example, tourists.
%COMMUNITY_ID%: Specifies the unique string identifying the community. This name is strictly an internal representation and does not get exposed in the user interface. For example, jdo__tourists.
%COMMUNITY_DESCRIPTION%: Includes a description of the community.
%COMMUNITY_CONTAINER%: Specifies the top-level container for the community. For example, jdo__touristsContainer.
%COMMUNITY_DP_PRIORITY%: Specifies the display profile merging priority given to the resulting community display profile. Each role is given a different value. By default, 1000 for the visitor role, 1005 for the member role, and 1010 for the owner role.
%COMMUNITY_SEARCH_URL%: Specifies the Search server URL for the community.
%COMMUNITY_CONTENTS_SEARCH_DB%: Specifies the search database for the community content.
%COMMUNITY_DISCUSSIONS_SEARCH_DB%: Specifies the discussions database.
%PORTAL_ID%: Specifies the ID of the portal. For example, portal1.

Template Descriptor File

Each template includes a resource bundle properties file which defines the meta-data associated with that template. The resource bundle is referred to as the descriptor file that can be localized. Each template descriptor file (must) define the following properties:

id: Specifies an unique ID of the template. The ID must match the template directory name. For example, Baseball for a template directory named Baseball with role templates (or XML files) for all three supported roles.
name: Specifies an user-friendly name used in the user interface (portal desktop) to identify the template. For example, Baseball Template.
description: Contains a verbose description of the template including the services it offers. For example, Baseball-themed template containing the following services: Player Statistics, Game Discussions, TV Schedule, and Online Chat.
tokens: Includes the list of tokens used in the template role files. This merely serves an informative purpose and is not required. For example, %COMUNITY_ID% %COMMUNITY_DESCRIPTION% %COMMUNITY_CONTAINER%.
previewImageURI: Specifies either the absolute or relative URI to the portal context. For example, http://images.domain.com/images/baseball.jpg. The relative URI must be relative to the portal web-app context path.

Example 9–2 Sample Descriptor File

id=Baseball
name=Baseball Template
description=Baseball-themed template containing the following services:
 Player Statistics, Game Discussions, TV Schedule, and Online Chat
tokens=%COMUNITY_ID% %COMMUNITY_DESCRIPTION% %COMMUNITY_CONTAINER%
previewImageURI=http://images.domain.com/images/baseball.jpg

Creating and Modifying a Template

To create a new or modify an existing template, following the instructions in this section. You can create a template in one of the following three ways:

Export the template, add content, and import the content using the psadmin utility.
Create content and import the content to overwrite existing template.
Add new files to existing templates.

To Create a New Template for Single Portal Environment

Go to the communityTemplateBaseDir.

Create a:
- New directory for the new template
- Copy an existing template to the new template directory
For example, type:
cd PortalServer-DataDir/portals/portal-URI/communitytemplates mkdir NewTemplate cp 2column/* NewTemplate/

Modify the role based display profile documents in the new template directory as needed.

For more information on the role based display profile documents, see Template Syntax and Semantics.

Create and edit the properties file to include the properties described in Template Descriptor File and save the file.

For example, to create a new properties files for the new template, type:
cp 2colimn.properties NewTemplate.properties
Or,
touch NewTemplate.properties
Note –
In order to see the newly added template, log out of any current portal session and re-login to see the change.

To Customize or Modify an Existing Template for Single Portal Environment

Go to the communityTemplateBaseDir/template directory and open the file you wish to modify.

Log out of any current portal session and re-login to see the change.

To Create a Template for Multi-Portal Environment

In a muti-portal environment (when there are more than one portal on the system), use PAR mechanism (as opposed to directly editing files in communityTemplateBaseDir) so that the change of community templates can be applied across multiple portals. This will allow all the portals to have the same set of community templates. If you do not wish to have synchronized environment across portals, use the instructions outlined in To Create a New Template for Single Portal Environment.

Either use psadmin export --type desktop to export desktop data (which includes community templates) and then export it so the content can be edited or, create a new PAR structure from scratch with only the community templates and no other desktop data.

Follow instructions in To Create a New Template for Single Portal Environment to edit content.

Create a new PAR file which contains:

   -+-- META-INF -- MANIFEST.MF
    |    
    +-- pbfiles -+-- communityTemplateBaseDir -+-- template1 -+-- deleted.xml
    |                                          |              |
    |                                          |              +-- disabled.xml
    |                                          |              |
    |                                          |              +-- member.xml
    |                                          |              |
    |                                          |              +-- owner.xml
    |                                          |              |
    |                                          |              +-- visitor.xml
    |                                          |
    |                                          +-- template1.properties
    |                                          |
    |                                          +-- template1_en.properties
    |                                          |
    |                                          +-- template1_fr.properties
    |                                          |
    |                                          +-- ...
    |
    +-- static -- community -- images -- template1.gif

Edit or add content as needed.

Create a new PAR file.

Use psadmin import subcommand to import the PAR content across all portals.

If you exported all desktop data, note that psadmin export subcommand will export all desktop data; if you create a new PAR structure from scratch with only the community templates, the command will only export community templates.

Tip –
For more information, see the psadmin export in Sun Java System Portal Server 7.2 Command-Line Reference.

Managing a Portal Server Community

This section provides information on creating and managing communities and community users from the Sun Java^TM System Portal Server administration console.

In Community Management page, a table lists the communities in the portal. Users can search for a community, and manage communities and community users.

The Community Management table contains the following information:

Name of the community
Number of users in the community
Indicates if the community is enabled or disabled
Indicates if the community is active or marked for deletion
Indicates if the community is listed or unlisted.
Indicates if the community is a membership restricted community or a unrestricted community.
Indicates if the community is a secure or a not a secure community.

For steps on how to manage communities and users, see Managing Communities and Users.

Managing Communities and Users

This section provides information on how to manage communities and users from Sun Java System Portal Server management console.

Use the following steps to manage communities and users:

To Search for a Community

Under the Portals tab, click a portal.

Click the Communities tab.

The Community Management page displays.

Type the name of the community in the Search for communities text box, and click Search.

Communities matching the search criteria are listed.

Tip –
You can do a wildcard search. For example, if your search criteria is *blog, all communities with the word blog anywhere in the name will be listed. Typing * will display all the communities.

To Create a Community

Under the Portals tab, click a portal.

Click the Communities tab.

The Community Management page displays.

Click the New button.

The Create Community page displays.

Type the values in the text boxes and make selections from the drop-down menus.

Click OK to finish.

To Manage Community Users

Under the Portals tab, click a portal.

Click the Communities tab.

The Community Management page displays.

Select a community.

Note –
Only one community can be managed at a time

Click Manage Current Users button.

The Manage Users page displays.

Click the Add button.

The Add Community User page displays.

Note –
If you want to change the status of existing users, go to step 7.

Type a user name in the User DN text box, and click Add.
1. If you do not know the user name, click Choose.
  
  The Select a User page displays.
2. Type the search criteria in the Search for Users text box, and click Search.
  
  Tip –
  You can do a wildcard search. For example, if your search criteria is *user, all user IDs with the word user anywhere in the name will be listed. Typing * will display all the users.
3. Specify a user, and click Select.
  
  The User DN text field in the Add Community User page displays the selected user name.
4. Click Add.

To change the status of an existing user, select a user.

Click one of the available option buttons.

The following options are available:
- Remove – Removes user from the community
- Assign Ownership – Assigns owner privileges to a community member
- Unassign Ownership – Owner privileges removed
- Ban – Banned from the community
- Remove Ban – Ban from the community removed

Click Back to return to Community Management page.

To Manage Pending Users

Under the Portals tab, click a portal.

Click the Communities tab.

The Community Management page displays.

Select a community, and click the Manage Pending Users button.

The Managing Pending Users page displays.

Select a user from the Awaiting Membership Approval table, and click the Approve or Deny button.

Click Back to return to Community Management page.

To Enable a Community

Under the Portals tab, click a portal.

Click the Communities tab.

The Community Management page displays.

Select a community.

Note –
Multiple communities can be selected.

Click the Enable button.

To Disable a Community

Under the Portals tab, click a portal.

Click the Communities tab.

The Community Management page displays.

Select a community.

Note –
Multiple communities can be selected.

Click the Disable button.

To Unmark a Community for Deletion

Under the Portals tab, click a portal.

Click the Communities tab.

The Community Management page displays.

Select a community under Name.

Note –
Multiple communities can be selected.

Click the Unmark for Deletion button.

To Mark a Community for Deletion

Under the Portals tab, click a portal.

Click the Communities tab.

The Community Management page displays.

Select a community under Name.

Note –
Multiple communities can be selected.

Click the Mark for Deletion button.

Note –
To permanently delete the community, use the command psadmin remove-community -u amadmin -f password_file -p portal --name community_name

To Edit a Community

Under the Portals tab, click a portal.

Click the Communities tab.

The Community Management page displays.

Click a community.

The Editing page displays.

Change the values and selections for the community.

Click Save.

Managing Community Webservice URL

Community search and administration functionality involves a community webservice. By default, the community webservice URL contains the same host as the first Portal instance. In a multi-node installation that uses a load balancer, you can change the community webservice URL to use the load balancer host.

To get and set the community webservice URL

Type the following in a terminal window:

./psadmin get-attribute -u amadmin -p portal-URI -m communities -a WebServicesURL

./psadmin set-attribute -u amadmin -p portal-URI -m communities -a WebServicesURL URL

amadmin

Specifies the administrator's distinguished name.

portal-URI

Specifies the portal ID.

WebServicesURL

Specifies the value for the WebServicesURL attribute. For example, the URL can be of the format http://foo.com:8080/communitymanagerwebservices/communitymanagerwebservices. Please note that the communitymanagerwebservices/communitymanagerwebservices part of the URL must not be changed.

Note –
There is no default value for the WebServicesURL attribute. By default, an empty value indicates that the host of the first Portal instance will be used.