Sie sind auf Seite 1von 100
atg Version 2007.1 Portal Administration Guide
atg
Version 2007.1
Portal Administration Guide

ATG One Main Street Cambridge, MA 02142 www.atg.com

ATG Portal Administration Guide Document Version

Doc2007.1 PORTALADMINv1 7/13/07

Copyright

Copyright © 1998-2007 Art Technology Group, Inc. All rights reserved.

This publication may not, in whole or in part, be copied, photocopied, translated, or reduced to any electronic medium or machine-readable form for commercial use without prior consent, in writing, from Art Technology Group, Inc. (ATG) ATG does authorize you to copy documents published by ATG on the World Wide Web for non-commercial uses within your organization only. In consideration of this authorization, you agree that any copy of these documents which you make shall retain all copyright and other proprietary notices contained herein.

Trademarks

ATG, Art Technology Group, and DYNAMO are registered trademarks of Art Technology Group, Inc.

ATG Wisdom, ATG Dynamo Application Server, ATG Adaptive Scenario Engine, ATG Scenario Personalization, ATG Portal, ATG Commerce, ATG Content Administration, ATG Data Anywhere Architecture, ATG Search, ATG Response Management, ATG Merchandising, ATG Knowledge, ATG Self Service, ATG Commerce Assist, ATG Advisor, ATG Forum and ATG Business Control Center are trademarks of Art Technology Group, Inc.

Microsoft, Windows and Word are the trademarks or registered trademarks of Microsoft Corporation in the United States and other countries. IBM, AIX, and MQ-Series are the trademarks or registered trademarks of IBM Corporation in the United States and other countries. Oracle is a registered trademark, and other Oracle product names, service names; slogans or logos referenced in this document are trademarks or registered trademarks of Oracle Corporation. Adobe Acrobat Reader is a registered trademark of Adobe. CORBA is a trademark of the OMG (Object Management Group). Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. Primus, and its respective logo, and Primus Knowledge Solutions, are trademarks, registered trademarks, or service marks of Primus.

This product includes software developed by the Apache Software Foundation (http://www.apache.org/).

EditLive Authoring Software Copyright © 2004 Ephox Corporation. All rights reserved. Includes code licensed from RSA Security, Inc. Some portions licensed from IBM are available at http://oss.software.ibm.com/icu4j/. Includes software developed by the Apache Software Foundation (http://www.apache.org/). Contains spell checking software from Wintertree Software Inc. The Sentry Spell Checker Engine © 2000 Wintertree Software Inc.

All other product names, service marks, and trademarks mentioned herein are trademarks of their respective owners. This publication may not, in whole or in part, be copied, photocopied, translated, or reduced to any electronic medium or machine-readable form for commercial use without prior consent, in writing, from Art Technology Group (ATG), Inc. ATG does authorize you to copy documents published by ATG on the World Wide Web for non-commercial uses within your organization only. In consideration of this authorization, you agree that any copy of these documents which you make shall retain all copyright and other proprietary notices contained herein.

No Warranty

This documentation is provided “as is” without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability, fitness for a particular purpose, or non-infringement.

The contents of this publication could include technical inaccuracies or typographical errors. Changes are periodically added to the information herein; these changes will be incorporated in the new editions of the publication. ATG may make improvements and/or changes in the publication and/or product(s) described in the publication at any time without notice.

Limitation of Liability

In no event will ATG be liable for direct, indirect, special, incidental, economic, cover, or consequential damages arising out of the use of or inability to use this documentation even if advised of the possibility of such damages. Some states do not allow the exclusion or limitation of implied warranties or limitation of liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you.

ATG One Main Street Cambridge MA 02142 617.386.1000 phone 617.386.1111 fax www.atg.com

ATG

Portal Administration Guide

µ

Contents

1 Getting Started

1

Installation

1

Starting up the Portal Application

1

Portal.paf

1

Portal.gears

2

Portal.<gearname>

2

Portal Web Applications

2

Accessing ATG Portal

3

Opening a Portal Page

3

Opening the Portal Administration Pages

4

Accessing the Default Portal

4

2 Administration Pages

5

Portal Administration Pages

5

Portal Administration Navigation

5

Communities Tab

6

Gears Tab

6

Styles Tab

7

Alerts Tab

8

Community Administration Pages

8

Community Settings Tab

9

Community Users Tab

9

Community Pages Tab

10

Community Gears Tab

10

Reset Buttons

10

3 Portal Configuration

11

Configuring Your Database

11

Configuring Your Repositories

11

Portal Repository Creation

11

Portal Repository Configuration

12

Profile Repository

12

Portal Personalization

12

Profile Template

12

Business Rules

13

Page Templates and Branding

13

Shared and Full Page Template

14

iii

ATG

Portal Administration Guide

µ

4

Layout Templates

14

Gear Title Template Files

14

Stylesheet Files

15

Additional Branding Files

15

Creating Style Element Templates

16

Localizing a Portal

16

Configuring E-mail Templates for Alerts

17

Portal and the Global Scenario Server

17

Community Administration

19

Community

19

Individual

19

Organization

19

Community Folders

20

Creating Community Folders

20

Deleting Community Folders

20

Reserved Community Names

20

Specifying a Home Community

21

Reserving a Web-Friendly Name

21

Community Roles

21

Global Roles

22

Relative Roles

22

Community Role IDs

23

Community Membership

23

Membership Settings

23

Canceling Community Membership

24

Adding and Removing Community Members

24

Working with Communities

24

Creating a Community

24

Making Gears Available to a Community

25

Limiting a Community’s Access to Gears

26

Editing a Community

27

Disabling a Community

27

Deleting a Community

27

Editing a Community Portal Page

28

Adding a Community Portal Page

29

Adding Gears to a Community Portal Page

30

Viewing a Community Portal Page

30

Deleting a Community Portal Page

30

Creating Communities from Community Templates

31

Using the Community Templates User Interface

31

Using the SpawnCommunity Tool

32

Automating the Portal Creation Process

34

Community Proposals

34

Creating a Workflow for Community Proposals

35

Creating a Scenario for Community Proposal Workflows

37

Creating a Community Proposal

37

iv

ATG

Portal Administration Guide

 

µ

 

Working with Community Membership Adding a Member to a Community Approving or Declining Membership Requests Enabling Membership Request E-mail Notification Assigning a Community Leader Role to a Member Adding a Guest to a Community Creating New Portal Users Searching for Members in an LDAP Repository

38

39

39

39

40

41

41

42

5 Portal Administration

43

Manifest Files Style Administration Page Templates Adding Page Templates to the PAF Layout Templates Adding Layout Templates to the PAF Gear Title Templates Adding Gear Title Templates to the PAF Color Palettes Adding Color Palettes to the PAF Stylesheets Adding Stylesheets to the PAF Gear Administration Gear Folders Gear Configuration Types Gear Installation Configuration Gear Instance Configuration Gear Parameter Configuration Adding Gears to the PAF Deleting a Gear from the PAF Sharing Gears in the PAF Configuring Alerts Creating New Administrative or Framework Alerts Configuring an Alert Deleting an Alert Customization Administration

43

44

44

44

44

45

45

45

45

46

46

46

47

47

47

47

47

48

48

48

49

49

50

50

51

51

6 Using Scenarios with ATG Portal

53

Using Portal Attributes in a Scenario Displaying a Gear in a Slot Creating a Slot to Display a Gear Creating Scenarios to Display Gears in Slots Portal Scenario Events and Actions Preconfigured Portal Scenarios

53

53

54

54

56

56

 

v

ATG

Portal Administration Guide

µ

7 Portal Access Control

59

J2EE Security

59

Community Security Administration

59

Setting Basic Access Levels for a Community

60

Setting Advanced Access Controls for a Community

60

Setting Community Access by Role

61

Page and Gear Level Access Control

62

Predefined Secured Areas

63

Portal Administration Pages

63

Community Administration Pages

63

8 Baseline Gear Administration

65

Baseline Gears Overview

65

Configuring Baseline Gears

66

Alerts Gear

67

Bookmarks Gear

68

Calendar Gear

69

Community Members Gear

70

Discussion Gear

70

Document Exchange Gear

71

Favorite Communities Gear

75

HTML Content Gear

75

Login Gear

77

Outlook Gear

77

Poll Gear

79

Quicklinks Gear

79

Repository Search Gear

80

Repository View Gear

81

Targeted Content (Slot) Gear

83

Web Services Client Gear

84

XML-Feed Gear

87

XML Protocol Gear

89

Index

92

vi

ATG

Portal Administration Guide

µ

1 Getting Started

This document provides guidelines for administering and configuring the Portal Application Framework, or PAF, for ATG Portal. The PAF serves as a structure for a series of customized Internet communities. Using the PAF you can create communities of users, joined by purpose or common interest. The PAF can provide these communities with specialized portals. Each portal can be customized for content, appearance, and functionality, on both the community and individual level. For more technical information intended for Java programmers, see the ATG Portal Development Guide.

The PAF provides two Web-based administration user interfaces: the Portal Administration, which system administrators can use to manage the portal and its communities as a whole, and the Community Administration, which community leaders can use to manage individual communities in the portal.

Access to Portals is controlled by a series of security measures based on community roles. A visitor’s role within a community determines that person’s ability to view content, interact with other users, and customize the appearance and content of the portal page.

Installation

Read the ATG Installation and Configuration Guide for information about how to download and install ATG Portal. Check the technical specifications at www.atg.com to see which operating systems, application servers, and database software you can run ATG Portal on.

Starting up the Portal Application

To use ATG Portal, you assemble an EAR file that includes the modules you want to use. Once you have an EAR file, you deploy it to the appropriate location and startup the Web application it contains. For information on assembling applications, see the ATG Programming Guide. Deploy and start your application according to the instructions in the manuals provided with your application server.

The following sections describe the Portal modules that you may want to specify during application assembly.

Portal.paf

The Portal.paf module contains the PAF itself. At a minimum, you must specify this module to use ATG Portal.

1

 

ATG

Portal Administration Guide

µ

Portal.gears

The Portal.gears module contains the collection of baseline gears as well as the PAF module. You must use this module to make the baseline gears available.

Portal.<gearname>

 

You use this module to make additional gears available to your portal visitors. For example, if you created a gear called productprices, you would include the module Portal.productprices.

Portal Web Applications

 

ATG Portal includes the following four J2EE Web applications:

 

Web Application

Module

Description

Archive

admin.war

PAF

The Portal Administration

settings.war

PAF

The Community Administration

 

portal.war

PAF

The default Portal

In addition, each of the baseline gears included in ATG Portal is a J2EE Web application, all of which are included collectively with the gears module, but any one of which can be included with its own module name:

Gear Name

Module Name

 

Alert

Alert

Bookmarks

bookmarks

Calendar Publisher

calendar

Community Members

contacts

Discussion

discussion

Document Exchange

docexch

Favorite Communities

communities

HTML Content

screenscraper

Login

user_registration

Outlook

exchange

2

ATG

Portal Administration Guide

µ

Poll

poll

Quicklinks

quicklinks

Repository Search

search

Repository View

repview

Targeted Content (Slot)

slotgear

Web Services Client

soapclient

XML Protocol

xmlprotocol

XML Feed

xmlfeed

Accessing ATG Portal

The first time you access ATG Portal, use admin as your user ID and admin as your password to enter the portal. This user has Portal Administrator authority. For security, you will eventually want to create new Portal Administrator user accounts and delete the admin user account.

Opening a Portal Page

To open a portal page, enter the URL into your Web browser. This URL is structured in the form of:

http://hostname:port/portalcontext/communityfoldername/communityname

/pagename

The elements of the URL are as follows:

Port

The default port number depends on the application server you are using. For example, for JBoss, the default is 8080. See the ATG Installation and Configuration Guide for specific information.

Portalcontext

The portal context is portal for the default portal

communityfoldername

The name of the community folder

Communityname

The name of the community that you want to view

pagename

The name of a specific page in the community. If no page name is specified, the default page for the community opens.

The portal page opens in the browser window.

3

ATG

Portal Administration Guide

µ

Opening the Portal Administration Pages

You can use the Portal Administration Pages to create communities and assign roles in your portal and to configure the appearance and content of the portal pages and communities. To use the Portal Administration Pages, enter the URL into your Web browser. This URL is structured in the form of http://hostname:port/portal/admin. Note that the port number depends on the application server you are using. See the ATG Installation and Configuration Guide for the default number. For example, the default URL on JBoss is:

http://hostname:8080/portal/admin

Accessing the Default Portal

If you use ATG Portal with the Portal.paf and Portal.gears modules, you can access an empty Portal application. This default Portal provides you with a starting point for Portal development. It defines the basic information (colors, templates, the admin user) needed to start building your own portal, but does not define any communities or community pages. To administer the default Portal and begin development of a new Portal:

1. Assemble an application that includes the Portal.gears module.

For information about assembling applications, see the ATG Programming Guide.

2. Deploy and start your application according to the instructions provided in your application server manuals.

3. Open the Portal Administration, as described in the Opening the Portal Administration Pages section, by pointing your browser to:

http://hostname:port/portal/admin

where hostname is the machine that runs your application server and port is the port number your application server uses to listen for HTTP requests. For the default port, see the ATG Installation and Configuration Guide.

4. Create a new community folder, new communities, and new community pages, as described in the Community Administration chapter.

4

ATG

Portal Administration Guide

µ

2 Administration Pages

You administer the PAF from two Web-based user interfaces called the Portal Administration Pages and the Community Administration Pages. From the Portal Administration Pages you can create communities, administer the content and appearance of the portal, and make gears and other features available to the portal’s communities. From the Community Administration Pages you can create the content, administer the membership, and configure the appearance of a specific community. The following sections describe these administration pages:

Portal Administration Pages

Community Administration Pages

Portal Administration Pages

The Portal Administration Pages provide access to all aspects of the PAF, as described below. If you are a Portal Administrator, you can reach the Portal Administration Pages at http://hostname:port/portal/admin. The default port number depends on the application server you are using. See the ATG Installation and Configuration Guide for port information. For example, on JBoss, the Portal Administration URL is:

http://hostname:8080/portal/admin

Portal Administration Navigation

The Portal Administration has two main navigation aids, the top navigation bar and the side navigation panel. When you open the Portal Administration Home Page, you see four main tabs in the navigation bar at the top. These are the:

Communities Tab

Gears Tab

Styles Tab

Alerts Tab

5

ATG

Portal Administration Guide

µ

ATG Portal Administration Guide µ As you work with the Portal Administration, this navigation bar continues

As you work with the Portal Administration, this navigation bar continues to be displayed, letting you switch immediately to another work area.

In addition, each of these four tabs has a navigation panel at the side. The side navigation panels link to particular tasks within the main tab’s work area.

Communities Tab

When you open the Communities tab, the Portal Administration displays the Available Communities page, which lists all of the communities in the portal. As the Portal Administrator, you have access to all of these communities, and can view and edit all of them. The side navigation panel in the Communities tab lists the tasks you can perform:

in the Communities tab lists the tasks you can perform: For more information on communities, refer

For more information on communities, refer to the Community Administration Pages section in this chapter and the Community Administration chapter.

Gears Tab

Gears provide content and functionality within the portal pages. When you open the Gears tab, the Portal Administration displays the Available Gears page, which lists all of the gears available in the PAF. You can use this page to configure existing gears. Any configuration done at this level applies to default instances of the gear. You can configure the gear at the community level to make community-specific changes in the gear instance. You can use the New Gear page to add more gears to the PAF.

The side navigation panel in the Gears tab lists the tasks you can perform:

6

ATG

Portal Administration Guide

µ

ATG Portal Administration Guide µ For more information on baseline gears, the set of prefabricated gears

For more information on baseline gears, the set of prefabricated gears provided with the PAF, refer to Gear Administration. For more information on developing your own gears, refer to the ATG Portal Development Guide.

Styles Tab

The Styles tab provides a set of style element tools you can use to standardize or customize the presentation of pages in your portal. These tools are page templates, layout templates, gear title templates, color palettes, and stylesheets. When you open the Styles tab, the Portal Administration displays the Page Templates page, which lists all of the page templates available in the PAF.

which lists all of the page templates available in the PAF. Page Templates Page templates supply

Page Templates

Page templates supply the underlying HTML and WML wrappers for the portal pages. The Page Templates tab lists all of the page templates available in the PAF. You can use this page to add more page templates to the PAF. For more information on page templates, refer to Page Templates and Branding in the Portal Configuration chapter.

Layout Templates

Layouts arrange the appearance of gears within the portal pages. The Layouts Templates page lists all of the layouts available in the PAF. You can use this page to add more layouts to the PAF. For more information on layouts, refer to Layout Templates in the Page Templates and Branding section of the Portal Configuration chapter.

Gear Title Templates

Gear titles provide a decorative title and border for gears appearing in a portal page. The Title area may contain an Edit control for Community Members to customize the gear. You can use this page to add more gear titles to the PAF. For more information on gear titles, refer to Gear Title Templates in the Style Administration section of the Portal Administration chapter and to Gear Title Template Files in the Page Templates and Branding section of the Portal Configuration chapter.

7

ATG

Portal Administration Guide

µ

Color Palettes

Color palettes provide color and background images within the portal pages. The Color Palettes page lists all of the color palettes available in the PAF. You can use this page to add more color palettes to the PAF. For more information on color palettes, refer to Color Palettes in the Style Administration section of the Portal Administration chapter.

Stylesheets

Stylesheets describe how the portal page is presented. The Stylesheets page lists all of the stylesheets available in the PAF. You can use this page to add more stylesheets to the PAF. For more information on color palettes, refer to Stylesheets in the Style Administration section of the Portal Administration chapter.

Alerts Tab

Alerts are messages generated by events occurring within the portal. Alert messages can be delivered through the Web channel, appearing in portal pages, or through the e-mail channel. Alerts can be either administrative alerts, which are messages that are generated from the Portal Administration pages, or framework alerts, which are messages that are generated from community pages in the portal. When you open the Alerts tab, the Portal Administration displays the Administrative Alerts page, which lists all of the administrative alerts available in the PAF.

The side navigation panel in the Alerts tab lists the tasks you can perform:

panel in the Alerts tab lists the tasks you can perform: You can create new administrative

You can create new administrative or framework alerts or configure existing alerts using the Portal Administration. See Configuring Alerts in the Portal Administration chapter for information about creating new alerts. See the Adding Gear Alerts chapter in the ATG Portal Development Guide for additional information about alerts.

Community Administration Pages

Each community has Community Administration Pages, which are an interface for community administration. The Community Administration Pages provide access to all aspects of the community, as described below. If you are a Community Leader or Portal Administrator, you can reach the Community Administration Pages by clicking on the Administer link that appears on each page of the community.

It is important to distinguish between the Community Administration Pages and the Communities tab of the Portal Administration. The Communities tab in the Portal Administration is where you create new

8

ATG

Portal Administration Guide

µ

communities. Once you have created a community, you can create pages for and administer the community in the Community Administration Pages.

When you open the Community Administration Pages, you see four main tabs in the navigation bar at the top. These are the:

Community Settings Tab

Community Users Tab

Community Pages Tab

Community Gears Tab

Users Tab • Community Pages Tab • Community Gears Tab As you work with the Community

As you work with the Community Administration, this navigation bar continues to be displayed, letting you switch immediately to another work area.

In addition, each of these four tabs has a navigation panel at the side. The side navigation panel links to particular tasks within the main tab’s work area.

Community Settings Tab

The Community Settings tab specifies the name, URL, default access settings, style elements, and customization settings for the community.

Community Users Tab

The Community Users tab specifies the membership of the community. There are six classes of community membership:

members

member organizations

guests

guest organizations

leaders

leader organizations

The Community Leader can use this page to create, add and remove users of any of these membership classes from the community.

9

ATG

Portal Administration Guide

µ

Community Pages Tab

The Community Pages tab specifies the content and layout of the pages in the community. The

Community Leader can use this page to create, edit and remove pages, and to edit the content and layout

of the community.

Community Gears Tab

The Community Leader can use the Community Gears tab to administer instances of gears used in the community’s pages.

Reset Buttons

A number of pages in the Community Administration include a reset button. This button resets the form

elements of the page to the most recently saved values. The reset button does not reset the default values once you have clicked the update or save button on the page.

10

ATG

Portal Administration Guide

µ

3 Portal Configuration

Once the PAF is installed, you must configure it to work with your production Web server and database. You must also update your template files to display your branding information and graphics. This chapter includes the following sections that describe various configuration options:

Configuring Your Database

Configuring Your Repositories

Business Rules

Page Templates and Branding

Localizing a Portal

Configuring E-mail Templates for Alerts

Portal and the Global Scenario Server

Configuring Your Database

ATG Portal may require some product-specific configuration to work with your database. See the Configuring Databases and Database Access chapter in the ATG Installation and Configuration Guide for information about how to configure database access and install the Portal database.

Configuring Your Repositories

You must configure the repositories for your PAF, as well as for any gears. For a general discussion of repositories, refer to the ATG Repository Guide.

Portal Repository Creation

The PAF requires a SQL repository to store the various components and gears that make up the PAF itself. The PAF automatically creates this repository during installation. The Nucleus address of the repository component is /atg/portal/framework/PortalRepository. For most portal applications, the default repository component and database script is sufficient. For custom implementations of the PAF, you can modify the PortalRepository definition file and database schema to create and extend repositories that suit your specific needs. However, ATG technical support cannot support any changes you make to the default PortalRepository definition file and database schema.

11

3

-

Portal

Configuration

ATG

Portal Administration Guide

µ

Portal Repository Configuration

A SQL repository uses cache modes to define how its repository items are cached. For evaluation and

development, the Portal repository is configured to use the simple cache mode. For deployment, you should set the cache mode for each of the item descriptors of the Portal repository to locked mode. You

can do this easily by enabling the liveconfig configuration layer before you go live with your Portal application. The changes needed in the PortalRepository definition file can be found at

<ATG2007.1dir>/Portal/paf/framework/liveconfig/atg/portal/framework/portalReposito

ry.xml. For more information about SQL repository cache modes, see the SQL Repository Caching chapter

of the ATG Repository Guide. For more information about liveconfig, see the ATG Installation and

Configuration Guide.

Profile Repository

Since a portal typically relies on user profile information to determine what information should be delivered to which users, in most cases you will want to customize your user profile repository to include item descriptors and properties that allow you to differentiate among different classes of users and store their portal preferences and other user information. See the Portal Personalization section for more information.

Portal Personalization

Registered visitors to the portal are recorded in the ATG profile repository. The profile repository stores information on each registered user, such as name, gender, and address. The profile repository is installed as part of the ATG platform, and is used by several different parts of the ATG product suite. For more information on the profile repository, refer to the Configuring the Profile Repository Component section of the Setting Up a Profile Repository chapter in the ATG Personalization Programming Guide. If you are using an LDAP-based profile repository, see the Setting Up an LDAP Profile Repository chapter in the ATG Personalization Programming Guide.

Profile Template

The profile repository requires a template to define users in the profile repository. The ATG platform features a default profile template that you can redesign to suit your needs. However, as you customize the profile template, be sure that your schema retains the item descriptors and properties that are required by the PAF and the baseline or custom gears you are using in your portal application. The PAF expects a profile item descriptor named user, with at a minimum properties named login, firstName,

and lastName

The PAF extends the default profile template to include new item descriptors (gearUser,

personalizedRegion, personalizedCommunity, personalizedPage) that store information about

how a user may have customized his or her portal pages. These profile template changes are added in the following file:

<ATG2007.1dir>/Portal/paf/config/atg/userprofiling/userProfile.xml

12

3

-

Portal

Configuration

ATG

Portal Administration Guide

µ

In addition, the Favorite Communities gear extends the default profile template to include a userCommunity property that describes the communities to which a visitor belongs. This property is added in the following file:

<ATG2007.1dir>/Portal/communities/config/atg/userprofiling/userProfile.xml

The Alerts gear extends the default profile template to include properties that store the user’s alerts and alert preferences. These profile template changes are added in the following file:

<ATG2007.1dir>/Portal/alert/config/atg/userprofiling/userProfile.xml

When you use the ATG platform with the Portal module, these files are included in your Dynamo CONFIGPATH and are combined with the other user profile template definition files that share its Nucleus

address of /atg/userprofiling/userProfile.xml.

You can add user information to your repository by editing the ATG platform user profile template, or by extending the template to include other tables. For more information on modifying the profile template, refer to the ATG Personalization Programming Guide.

Business Rules

ATG Portal can use ATG Scenario Personalization to provide customized content based on the scenarios that you create. For more information on personalization, alerts, and scenarios, refer to the ATG Personalization Programming Guide and the ATG Personalization Guide for Business Users.

Page Templates and Branding

ATG Portal includes a set of style elements, including templates and images, that you can use to familiarize yourself with the structure and conventions of the PAF. You can change the appearance of your portal pages and insert your own portal branding by making copies and editing the JSP and image files, or by creating your own. Once you are familiar with the style elements, you can create new ones and add them to the default versions. The recommended way for you to brand your portal is to create a new Web application containing your new branded template files.

The default storage location for JSP page template files is in the

<ATG2007.1dir>/Portal/paf/starter-portal/paf-dar/portal/templates folder. Note that in

many cases there are separate versions of the templates for HTML and for WML. Also note that there is a folder named <ATG2007.1dir>/Portal/templates. The templates in that folder are there for backwards compatibility with ATG 5. They should not be used as a basis for page development in the ATG platform. For more detailed information about creating and using style elements, see the Style Administration section in the Portal Administration chapter of this guide and the Customizing Portal Appearance section of the Creating a Custom Portal chapter of the ATG Portal Development Guide.

13

3

-

Portal

Configuration

ATG

Portal Administration Guide

µ

Shared and Full Page Template

The shared and full page template (<ATG2007.1dir>/Portal/paf/starter-portal/paf- dar/portal/templates/page/html/shared.jsp and <ATG2007.1dir>/Portal/paf/starter- portal/paf-dar/portal/templates/page/html/full.jsp) are the primary template file, and

function as the outermost wrapper for the page. These page templates specify the header and footer HTML tags for the dynamically generated page.

Layout Templates

The layout template file specifies the layout of the page, creating a portal page framework for the placement of your gears. ATG Portal includes four layout templates for use with your portal. The default

storage location for layout template files is the <ATG2007.1dir>/Portal/paf/starter-portal/paf-

dar/portal/templates/layout folder. For information on creating your own page layouts and templates, refer to the Customizing Portal Appearance section of the Creating a Custom Portal chapter in the ATG Portal Development Guide.

100.jsp Template

This template creates a page with one column spanning the full width of the page.

25_50_25.jsp Template

This template creates a page with three columns. The leftmost and rightmost columns span a quarter of the page each. The center column spans fifty percent of the page width.

25_75.jsp Template

This template creates a page with two columns. The left column spans a quarter of the page width. The right column spans the remaining seventy-five percent of the page width.

75_25.jsp Template

This template creates a page with two columns. The left column spans seventy-five percent of the page width. The right column spans the remaining quarter of the page width.

region.jspf

Each layout template defines a table, the cells of which each contain a separate gear. The layout template file calls the region template file once for each table cell in the page, until it has formatted all of the cells

in the page. The region template file specifies the formatting of regions within the portal page. A region is

defined as an individual table cell.

Gear Title Template Files

A gear is rendered in stages. First the titlebar.jsp file renders the title bar above the gear. The

titlebar_pre.jsp creates the table that contains the gear. Then the gear itself is rendered, and the titlebar_post.jsp closes the table. The default storage location for gear title template files is the

<ATG2007.1dir>/Portal/paf/starter-portal/paf-dar/portal/templates/titlebar folder.

14

3

-

Portal

Configuration

ATG

Portal Administration Guide

µ

titlebar.jsp

The gear title template file specifies the title formatting at the gear level, providing a decorative title and border for the gear. The gear title area may also contain an Edit control for Community Members to customize the gear, if the gear and the community allow customization. The gear title template is used for all the gears in a given community.

titlebar-pre.jsp

The gear pre-treatment template creates an HTML table to contain the gear itself.

titlebar-post.jsp

The gear post-treatment template closes the HTML table created by the titlebar-pre.jsp template file.

Stylesheet Files

A simple cascading stylesheet is located at <ATG2007.1dir>/Portal/paf/starter-portal/paf-

dar/portal/templates/style/css. See the Style Administration in the Portal Administration chapter for information about adding new stylesheets to your portal application.

Additional Branding Files

You can also customize the login, logout, registration, error, and authentication pages. This allows you to ensure that these pages match the design and branding of your portal. Customizing these files requires knowledge of JSP.

Files

File Name

Location

Login

login.jsp

<ATG2007.1dir>/Portal/paf/starter-

portal/paf-dar/portal/userprofiling

Logout

logout.jsp

<ATG2007.1dir>/Portal/paf/starter-

portal/paf-dar/portal/userprofiling

Registration

register.jsp

<ATG2007.1dir>/Portal/paf/starter-

portal/paf-dar/portal/userprofiling

Error

error.jsp

<ATG2007.1dir>/Portal/paf/starter-

portal/paf-dar/portal

Access Denied

accessDenied.jsp

<ATG2007.1dir>/Portal/paf/starter-

portal/paf-dar/portal/access

Community Offline

offline.jsp

<ATG2007.1dir>/Portal/paf/starter-

portal/paf-dar/portal/access

15

3

-

Portal

Configuration

ATG

Portal Administration Guide

µ

Creating Style Element Templates

You can create additional templates to determine the style and structure of your portal pages. Only developers familiar with Java server pages should attempt to do this. Create copies of the original style element files, and move them to a separate directory. Using the copies as an example, and, referring to ATG Portal Development Guide, you can create new style element templates. The original template files are

stored in the templates folder in <ATG2007.1dir>/Portal/paf/starter-portal/paf-dar/portal.

Once you have created the new style element files, refer to Style Administration in the Portal Administration chapter to make the style element available to communities.

Localizing a Portal

If you want to create a portal application that can serve users in different languages and locales, you should read the Internationalizing a Dynamo Web Site chapter in the ATG Programming Guide. This section describes a few considerations that are specific to an ATG Portal application.

You can enable support for additional locales and change character encodings used for the entire portal. This is done by copying, renaming, and (if you want to change a locale’s default character set) editing a file that is provided with the Portal module. Use the following procedure:

1. In your <ATG2007.1dir> directory, create the following directory branch:

<ATG2007.1dir>/home/locallib/atg/portal/framework

2. Locate and copy the LocaleSettings.properties file within your ATG installation. The file is in:

<ATG2007.1dir>/Portal/lib/classes.jar

3. Place the copy of the LocaleSettings.properties file into the new directory you created, and make additional copies for each locale you want to add to the portal.

4. Add the language and/or locale setting to the filename, as follows:

LocaleSettings_language_country.properties

where the required language is the desired Java language code (which is the same as the ISO two-letter language code) and the optional country is the desired Java locale code (which is the same as the ISO two-letter country code). For example, if you want to add French, you would name your file LocaleSettings_fr.properties and if you wanted to add French with a country of Canada, you would name your file

LocaleSettings_fr_CA.properties. For more details, refer to the Java

internationalization documentation.

5. If you also want to change the default character set for the language or language/locale combination, open the file and add the non-default character set.

The following sample illustrates how you would change Japanese with an EUC character set to Japanese with an SJIS character set:

16

3

-

Portal

Configuration

ATG

Portal Administration Guide

µ

# Version: $Change: 219562 $$DateTime: 2001/11/12 13:47:44 $

# If you want to override the default Java-chosen charset for this locale

# add a line charset=the-charset to this file.

# For example for Japanese using SJIS in place of EUC:

# charset=Shift_JIS

# Or for Unicode:

# charset=UTF-8

charset=Shift_JIS

In addition, you need to make sure that the gears you want to use in your localized portals are also localized into each of the locales you want to support. See Localization Considerations in the Designing a Gear chapter of the ATG Portal Development Guide.

Configuring E-mail Templates for Alerts

Many events in ATG Portal can trigger alerts, which can be sent by Web channel for display in a portal page or by e-mail. To use e-mail alerts, you need to set the messageFrom and messageReplyTo fields in the Portal e-mail templates to a valid e-mail address for your organization. The following e-mail templates are included in the Portal module.

/alert/src/alert.war/email/DefaultEmail.jsp

/calendar/src/src/calendar.war/email/CalendarEventCreatedEmail.jsp

/calendar/src/src/calendar.war/email/CalendarEventDeletedEmail.jsp

/calendar/src/src/calendar.war/email/CalendarEventEditedEmail.jsp

/calendar/src/src/calendar.war/email/CalendarEventViewedEmail.jsp

/discussion/src/src/discussion.war/email/NewForumEmail.jsp

/docexch/src/src/docexch.war/email/DocCreatedEmail.jsp

/docexch/src/src/docexch.war/email/DocDeletedEmail.jsp

/docexch/src/src/docexch.war/email/DocUpdatedEmail.jsp

/docexch/src/src/docexch.war/email/DocViewedEmail.jsp

/screenscraper/src/doc/Portal/email/FullPageURLChangedEmail.jsp

/screenscraper/src/doc/Portal/email/SharedPageURLChangedEmail.jsp

You may have custom e-mail templates as well. If you do not supply valid e-mail addresses, no alerts will be sent by e-mail and the portal will generate errors if e-mail alerts are configured.

Portal and the Global Scenario Server

The Portal Alerts system uses the ATG platform Global Scenario Server. Because running the Global Scenario Server places an additional burden on your server, consider configuring the global servers to not accept any user sessions. Do this by setting the drpEnabled property to false in the /atg/dynamo/Configuration component for that server instance. For additional material on configuring ATG products for improved performance, programming efficiently and troubleshooting server performance problems, refer to the ATG Installation and Configuration Guide.

17

3

-

Portal

Configuration

ATG

Portal Administration Guide

µ

18

3

-

Portal

Configuration

ATG

Portal Administration Guide

µ

4 Community Administration

Most visitors to your portal belong to one or more communities. By creating separate communities within your portal, you can determine what access your portal visitors have to content and functionality. You can even specify community-specific settings for the gears that appear on the portal page. For example, you could customize a weather forecasting content gear to provide local weather information for a remote office.

Each community has its own pages, with customized content, layout, and colors. The more your visitors tell you about themselves and their preferences, the more specific and customized their communities can become.

Community

A community is a collection of portal users and content. A typical community shares a common purpose or hobby. The community might be a company department, such as a human resources group, or it might be a group of users with a common interest, such as a social group. Each community has its own portal pages, with content and functionality specific to the needs and interests of the community.

Individual

An individual is a unique visitor to the portal site. Depending on the permissions set by the Community Leader, individuals can view content, and interact with other individuals in their community. Individuals can belong to any number of communities. The individual’s role can also vary from community to community.

The Community Leader can allow individuals to customize their portal pages on an individual level. As an individual, you can set the color palette of your personal portal, the layout of your gears, and which gears and content appear in your portal page.

Organization

An organization is a group of individuals that are members of a common group. Community membership can be assigned on an organization membership basis. Once an employee is a member of an organization, that employee has access to all communities that the organization belongs to. For example, all HR employees might be members of the HR organization. You could add a new hire to the HR organization, and that new hire would automatically receive membership to all the communities in which the HR organization has membership. You can designate an organization to have guest, member, or leader access to a community.

19

ATG

Portal Administration Guide

µ

Community Folders

Community folders organize communities hierarchically within the PAF. Visitors to the portal site see the Community name, rather than the name of the community folder. Each community folder contains both a name and a Web-Friendly URL. The Web-Friendly URL is used to generate the URL for the Community pages. Consequently, the Web-Friendly URL can contain only alphanumeric characters. Spaces and symbol characters in the Web-Friendly URL are removed, because they would otherwise cause the page to generate an error.

Creating Community Folders

A Portal Administrator can create a new community folder in the Portal Administration. To create a new

community folder:

1. Open the Communities tab in the Portal Administration.

2. Click the New Community Folder link in the side navigation bar.

The New Community Folder page opens.

3. Select the parent folder for the new folder. The root folder is named Default Community Folder.

4. Enter the name and Web-Friendly URL for the new folder and click Save. Remember that the Web-Friendly URL can contain only alphanumeric characters. Non- alphanumeric characters will be stripped out.

Deleting Community Folders

If you want to delete a community folder, you must first delete all of its child folders and communities using the Communities tab in the Portal Administration. Once you’ve done this, to delete a community folder, use the ATG Control Center:

1. Start the ACC and open the Portals > Portal Repository window.

2. Display Items of type Community folder, then click List.

3. Select the parent folder of the folder you want to delete. Select its Child folders

property and click the

button.

4. Select the folder that you want to delete and click Remove.

5. Click OK. You are returned to the Portals > Portal Repository window.

6. Select the folder that you want to delete. Be sure that its Child folders property is empty. Right click on the folder you want to delete and select Delete from the menu. Click Yes in response to the Delete Confirmation prompt.

Reserved Community Names

You can reserve community Web-Friendly names for administrative use. The Portal Administrator can reserve other names using the ACC, as described in the Reserving a Web-Friendly Name section below.

20

ATG

Portal Administration Guide

µ

For more information on the ACC, refer to the ATG Installation and Configuration Guide. If a user tries to create a community using a name included on reserved list, the user receives an error, and cannot use the name.

Note that you should not use as a URL any of the file names found in

<ATG2007.1dir>/Portal/paf/starter-portal/paf-dar/portal/, including access, portlets,

templates, or userprofiling.

Specifying a Home Community

The Web-Friendly name home is special for communities. If a community has the Web-Friendly name home then it can be accessed through a URL by specifying just the path of the Community Folder, and not the complete URL. For example if you have a Community Folder named /foo and a community named Bar, which has a Web-Friendly name home then you can access the Bar community via the URL /foo/ instead of /foo/home. The advantage to naming a community home appears when you have multiple communities in the same folder. The home community becomes the primary community for that community folder, and is the default community when visitors enter the community folder URL. There can be only one home community in a given community folder.

Reserving a Web-Friendly Name

The PortalPropertyManager component maintains a list of reserved names for the portal. If you have Administrator privileges, you can edit this list in the ATG Control Center. To add a reserved name:

1. Open the ATG Control Center.

2. Select Pages and Components, followed by Components by Path.

3. Navigate to /atg/portal/admin/PortalPropertyManager.

4. Within the PortalPropertyManager module, select the reservedCommunityNames

property.

The default settings are admin and settings.

5. Add the new reserved names to the property, and click Save.

The new names are added to the list of reserved names.

Community Roles

Most visitors to your portal will belong to one or more communities within that portal. When a visitor belongs to a community, the visitor takes on a role within that community. The scope of that role can vary from anonymous access visitor to global Portal Administrator. Your role determines your ability to customize your portal, view content, and to interact with other users. At administrative levels, your role also determines your ability to grant and restrict the authority of other users.

21

ATG

Portal Administration Guide

µ

Global Roles

Administrators with global roles have authority across all portals and communities within the PAF. Administrators with global roles are responsible for installing and maintaining the PAF, as well as creating the communities that populate it.

Portal Administrator

The Portal Administrator creates and deletes community folders and communities, and manages gear folders. The Portal Administrator is responsible for day-to-day issues of portal and community membership administration using the administrative interface provided by the PAF. These tasks include adding new gears and style elements to the portals, and maintaining and updating existing portals. Portal Administrators have authority over all of the communities in the PAF, including those created by other Portal Administrators.

The Portal Administrator is the only role that has access to the Portal Administration Pages. These pages allow access to the gears and style elements that make up the PAF.

Relative Roles

Relative roles apply to leaders, members, and guests of a particular community. The administrative authority granted by a relative role applies only to the community in which it was given, and does not apply to any other community. The ability of relative role holders to administer their communities and personal portals is subject to the limits set by the Portal Administrator.

Community Leader

The Community Leader assigns new members to the community, and chooses the default gears, color, and layouts for the community’s pages. Community Leader status is assigned by the Portal Administrator. Existing Community Leaders can also assign Community Leader status to other Community Members. Community Leaders can also configure default gear settings and permissions for their communities.

Community Member

A Community Member is one of the most common roles in a community. Once they have logged in,

members typically have full read/write access to the community. For example, a community member could read and write to a community discussion board. Members usually also have the ability to

customize the appearance and content of their personal portals.

Community Guest

A Community Guest is a logged in user who has permission to view a community portal page, but does

not have full membership access to that portal. For example, a company’s Sales community might have

permission to view the portals of other communities as guests of those communities. The ability of Community Guests to interact with portals is subject to the security settings of the portal.

Registered User

A registered user visitor is a visitor that has logged in to the portal, but does not have a role as a leader or

member within the community. Depending on the permissions in the PAF, registered user access may not be permitted in your portals and communities.

22

ATG

Portal Administration Guide

µ

Anonymous Access

An anonymous access visitor is a visitor that has not logged in to the portal. Depending on the permissions in the PAF, anonymous access may not be permitted in your portals and communities. Once anonymous access visitors log in to the portal, they automatically lose anonymous access status and assume their community roles, or registered user status if the visitors do not have community roles.

Community Role IDs

The PAF creates a role ID for each type of member role when the community is created. These role IDs are stored in the PAF repository in the form of <communityID>-<roletype>. For example, a member of the Tennis Community (community number 10004) might appear as 10004-member. Although you can view these role IDs using the ACC, you cannot edit the role ID without making the role unrecognizable to the PAF, and causing errors in the community.

Community Membership

Community membership can be handled in a variety of manners, depending on how much administrative involvement the community requires. You can specify the membership settings of a community from the Community Settings and Community Users tabs of the Community Administration Pages.

Membership Settings

The Community Settings tab lets you choose one of these membership settings:

Allow Membership Requests and Automatically Accept New Members

This setting allows visitors to request membership in the community. The PAF automatically accepts these requests without checking with the Community Leader. Visitors seeking membership apply by clicking the Become a member link on the community page. This setting allows the greatest public access to the portal page.

Allow Membership Requests and Notify Community Leaders

This membership setting allows visitors to request community membership, but withholds membership until the Community Leader has approved the request. Visitors seeking membership apply by clicking the Become a member link on the community page. When a visitor applies for membership, the visitor’s name and e-mail address appear on the Approve/Decline Membership Requests page in the Community Users tab. The Community Leader can then use that page to either approve or decline the membership request. This setting allows conditional public access to the portal page.

Do Not Allow Membership Requests

This membership setting prevents visitors from applying for membership at all. The Portal Administrator and Community Leaders can still grant community membership.

23

ATG

Portal Administration Guide

µ

Canceling Community Membership

Community Members can terminate their membership in the community by clicking the Unsubscribe link on the community page. Once they are unsubscribed, former members can reapply for membership by following that community’s standard membership process.

Adding and Removing Community Members

From the Community Users tab, a Community Leader can add or remove users and organizations as community members or leaders or approve or decline membership requests from guest users. You can also use the Create user link on the Community Users tab to add new user profiles to the Profile repository. Once you have created a new user profile, that user can then become a community member. Note that when you remove users as community members, you are not removing their profiles from the profile repository.

Working with Communities

The Portal Administrator handles community-level tasks from the Portal Administration Pages, including:

Creating a Community

Limiting a Community’s Access to Gears

Editing a Community

Disabling a Community

Deleting a Community

A Community Leader performs other community tasks in the Community Administration Pages,

including:

Editing a Community Portal Page

Adding a Community Portal Page

Adding Gears to a Community Portal Page

Viewing a Community Portal Page

Deleting a Community Portal Page

In addition, Community Leaders can use the Community Administration Pages to control access and

assign community roles to users, as described in the Working with Community Membership section in this chapter.

Creating a Community

The first step to creating a portal is creating a community. Each community is a group of users for whom the portal is designed. The community is, in effect, your audience. Communities are created by Portal Administrators, using the Communities tab in the Portal Administration.

24

ATG

Portal Administration Guide

µ

1. Enter the Portal Administration and click on the Communities tab.

2. Click New Community.

The New Community Page opens.

3. Select or create a folder for the community.

The community can reside within an existing folder, or you can create a new folder for the community.

4. Enter a Community Name and a Web-Friendly URL.

The Community Name is used in the portal and the Portal Administration to refer to the community. The Web-Friendly URL is used in generating the URL for the Community pages. As a result, non-alphanumeric characters are stripped out of the Web-Friendly URL.

You can also specify other settings for the new community now, or you can specify them later as you develop the community; these are described in the Editing a Community section.

5. Click Save.

The community is created, but is left inactive.

6. To make the community available online, select Active from the Status dropdown list on the New Community page in the Portal Administration or the Community Settings Page in the Community Administration and click Update.

You can also create multiple similar communities using a community template. For example, if you are creating a portal for an organization with many local branches, you can create a community for one branch, using the procedure described in this section. You can then create a community template based on this community, then use the template to create a similar community for each branch. For a description of how to make and use a community template, see Creating Communities from Community Templates.

Making Gears Available to a Community

Before you can add a gear to a portal page, the gear must first be made available to the community. To make a gear available:

1. The gear must be added to the PAF. See Adding Gears to the PAF in the Portal Administration chapter.

2. The gear’s folder must be made available to the community, using the gear folders link for the community on the Available Communities page in the Portal Administration. See the Limiting a Community’s Access to Gears topic in this section.

3. Make an instance of the gear available. Enter the Community Administration for the community and click the Community Gears tab.

4. Click the Select New Gears option in side navigation panel of the Community Gears tab. The Add gears page opens.

5. Click the select >> link for the gear you want to make available. The Configure Gear page opens.

25

ATG

Portal Administration Guide

µ

ATG Portal Administration Guide µ 6. Enter a name and description for this instance of the

6. Enter a name and description for this instance of the gear.

7. Select whether this gear should be shared with other communities and which users the gear should be visible to. Click Done.

Limiting a Community’s Access to Gears

By default, a community has access to all gear definition folders and hence has access to all gears. If necessary, you can limit the access of any community to the gears contained in specific folders. For example, if you had a gear containing sensitive financial information, you might want to prevent all communities except the Accounting community from having access to the gear. To limit gear access:

1. Enter the Portal Administration and click on the Communities tab.

2. Select the community for which you want to limit gear access and click its gear folders link.

The Assign gear folders to the Community page opens.

3. Click the Select Folders below radio button and then check only the gear folders to which you want the community to have access.

4. Click Save.

Note that if a gear already exists in the community, this procedure will not remove that gear from the community. To remove access to a gear that already exists in a community, you need to:

1. Remove the gear from each community page on which it appears.

26

ATG

Portal Administration Guide

µ

2. Use the Community Gears tab of the Community Administration to delete the gear instance.

Editing a Community

Once you have created a community, a Portal Administrator or Community Leader can edit it to change settings for the community and that community’s portal page.

1. Enter the Portal Administration and click on the Communities tab.

2. Locate the community that you want to edit and click the edit link next to the community name.

Or, enter the Community Administration for the community and click the Community Settings tab.

The Community Settings Page in the Community Administration opens.

3. Specify a Description and Request for membership options for the new community.

4. Specify Page template, Style, Gear title template and Customization options for this community’s portal pages.

5. If you want to make the community visible to members, set the community’s Status option to Active.

6. Click Update.

The settings you have specified are applied to the community and the Communities page opens.

Disabling a Community

You can disable a community, preventing all access to that community.

1. Log in to the Portal Administration Pages and click on the Communities tab.

2. Locate the community that you want to edit and click the edit link next to the community name.

Or, enter the Community Administration for the community and click the Community Settings tab.

The Community Settings Page opens.

3. To disable the community, set the Community Status option to Inactive.

4. Click Update.

The settings you have specified are applied to the community. If a user tries to visit the community, the portal will display a page that says this community is offline.

Deleting a Community

A Portal Administrator can also delete an entire community. You should never delete a community using the ATG Control Center; instead, use the Portal Administration. To delete a community:

27

ATG

Portal Administration Guide

µ

1. Open the Communities tab in the Portal Administration and click the delete link for the community.

2. A confirmation message appears, warning “Are you sure you want to delete the community <name>? Deleting this community will also delete any of this community’s shared gears from other communities.” Click on the Yes button to delete the community and all its pages.

Deleted communities will appear as nulls in the userCommunities property of a user profile in the ACC.

Editing a Community Portal Page

Each community has its own portal pages. A default page is created when you create the community. You can redesign this page to suit the needs of that particular community. To edit an existing page:

1. As a Portal Administrator, log in to the Portal Administration and click on the Communities tab. Locate the community whose page you want to create, and click the edit link next to the community name. Or, as a Community Leader, click on the Administer link on the community’s home page.

The Community Settings Page opens.

2. Click on Community Pages in the top navigation bar.

The Community Pages page opens, displaying all of the portal pages that belong to the community.

3. Select the page that you want to edit and click edit.

The Edit page for that portal page opens.

and click edit . The Edit page for that portal page opens. Use the Basics tab

Use the Basics tab in the Edit Page to change the page’s name or URL, set the access permissions, and specify whether users are allowed to customize the page. Customization lets users modify the appearance of their view of the page. It can also

28

ATG

Portal Administration Guide

µ

let them delete from their view gears that the Community Leader wants them to see, however.

4. Use the Gears tab in the Edit Page to add and remove gears from the portal page. See Adding Gears to a Community Portal Page for more details.

5. Use the Layout tab in the Edit Page to specify a layout template and the placement of gears within the portal page. Click Update to apply your layout to the page.

6. Use the Color tab in the Edit Page to specify the color palette to use on the portal page. Click on a color theme to preview the color palette, then click Update to apply that palette to the page.

Adding a Community Portal Page

Once you have created a community, you can create additional pages for that community.

1. As a Portal Administrator, log in to the Portal Administration Pages and click on the Communities tab. Locate the community to receive the new page, and click the edit link next to the community name.

Or, as a Community Leader, click on the Administer link on the community’s home page.

The Community Settings page opens.

2. Click on Community Pages in the navigation bar.

The Current Pages page opens, displaying all of the portal pages that belong to the community.

3. Click on the Create New Page link in the side task bar.

The Create New Page page opens.

4. Enter a name for the page.

5. Choose a position number from the dropdown list. The position number indicates the place of the page in the list of all community pages.

6. Enter a Web-Friendly URL. The Web-Friendly URL can contain only alphanumeric characters. Spaces and symbol characters cause the Create New Page page to generate an error. You can click the Generate URL button to automatically generate a URL based on the page name you entered.

7. Choose who can access the page by selecting a radio button under Make visible to.

8. Check the appropriate box if you want to permit users to customize the page or if you want to make this page the default page for the community.

9. When you have finished editing the portal page, click Update.

The changes you specified are made and the Current Pages page of the Community Pages tab opens.

29

ATG

Portal Administration Guide

µ

Adding Gears to a Community Portal Page

When you create a community portal page, you can add gears to those already included in the page template. To add a new gear to a page:

1. Navigate to the Gears tab on the Edit Page for the page, as described in the Editing a Community Portal Page section.

2. Check the boxes of the gears you want to include in the page and click Update.

3. Use the Layout tab on the Edit Page to arrange the position of gears in the page.

Note that only those gears that have already been made available to the community are displayed in the Gears tab of the Edit Page. To make a gear available to the community, a Portal Administrator must add it to the PAF using the Gears tab in the Portal Administration and make sure that the gear folder that contains the gear is itself available to the community. See Adding Gears to the PAF in the Portal Administration chapter. Next, a Community Leader must add an instance of the gear to the community. See Making Gears Available to a Community in this chapter.

Viewing a Community Portal Page

You can view a community portal page using the Portal Administration. When you view a page using the preview link in the administrator pages, you see the default version of those pages, regardless of any customization you may have applied to your own individual pages in the community. The preview link only appears for communities that are currently active. To view an inactive community, change its online status to active.

1. As a Portal Administrator, log in to the Portal Administration and click on the Communities tab.

2. Locate the community you want to view, and click the preview link next to the community name.

The default version of the community page opens in your browser window.

Alternatively, you can view a community portal page as a Community Leader:

1. Enter the Community Administration for the community whose page you want to view.

2. Click the Community Pages tab.

3. Click the view link for the page you want to view.

The default version of the community page opens in your browser window.

Note that if you have changed the portal’s context root in its deployment descriptor (application.xml), you also need to change the value of the contextPath property in the /atg/portal/framework/Portal component. Otherwise, the preview feature in the Community Administration will not work correctly.

Deleting a Community Portal Page

You can remove pages from a community. As a Portal Administrator or Community Leader, removing pages from a community affects the entire community. If a Community Member deletes a page, only that

30

ATG

Portal Administration Guide

µ

Member’s pages are affected. Once a Community Member deletes a page, however, that Member cannot restore the page to his or her own portal pages, even though the page still is available to other Community Members.

1. As a Portal Administrator, log in to the Portal Administration and click on the Communities tab. Or, as a Community Leader, click on the Administer link on the community’s home page.

2. Locate the community whose page you want to delete, and click the edit link next to the community name.

The Community Settings page opens.

3. Click on Community Pages in the navigation bar.

The Community Pages page opens, displaying all of the portal pages that belong to the community.

4. Select the page that you want to remove and click delete. Confirm the deletion by clicking the Yes, Delete button.

The portal page is deleted.

Creating Communities from Community Templates

ATG Portals provides two methods for copying an existing community to make multiple similar communities. You can do this using the Community Templates and New Community Template pages in the Portal Administration, or you can do this using a command line tool named SpawnCommunity. Using community templates through the Portal Administration may be easiest when you have just a few new communities to create based on a template. Using the SpawnCommunity tool may be easier if you have a large number of new communities to create.

Once you’ve created a community template, you can use the ATG Portal Process Automation (Portal.ppa) tools to create workflows that can automate the process of creating new communities from the template. See Automating the Portal Creation Process for more information.

Using the Community Templates User Interface

Creating a New Community Template

To create a new community template using the Portal Administration:

1. Click the New Community Template link on the main Communities page in the Portal Administration.

2. Click the save as template link to create a new community template based on an existing community.

3. Enter a name for the new template and click Save.

31

ATG

Portal Administration Guide

µ

Creating a New Community from a Template

Once you’ve created a community template based on an existing community, you can create new similar communities based on the template. To create a new community based on a template:

1. Click the Community Templates link on the main Communities page.

2. Click the spawn community link for the community template you want to use.

3. On the Spawn new community from template page, enter a name and other information for the new community. Click Save.

Using the SpawnCommunity Tool

You can create new communities from a command line using the SpawnCommunity tool. You can find UNIX and Windows versions of this tool in the <ATG2007.1dir>/Portal/PDK/ManifestLoader folder.

To create a new community using the SpawnCommunity tool:

1. Create a new community template using the Portal Administration, as described in the Using the Community Templates User Interface section.

2. Go to the Community Templates page and click the export link for the community template you want to use. This creates an XML file that represents the community template. You need to pass this XML file to the SpawnCommunity tool.

3. Run the SpawnCommunity tool. The syntax and arguments of the SpawnCommunity tool are described below.

A new community is created, taking its values from the community template. You can then edit the gears and pages of the new community as needed. Note that you can pass arguments to the SpawnCommunity tool to override many of the parameters of the community template.

The SpawnCommunity tool uses the following syntax:

SpawnCommunity.sh -template COMMUNITY_TEMPLATE -name COMMUNITY_NAME -url COMMUNITY_URL <optional arguments>

SpawnCommunity Arguments

The SpawnCommunity command takes the following arguments:

Argument

Description

Default Value

-template

The template XML file exported from the Portal Administration.

Required. Use the pathname of the template file, which can be either an absolute pathname or a pathname relative to the directory from which you run

SpawnCommunity.

32

ATG

Portal Administration Guide

µ

-name

The name of the new spawned community.

Required. No default.

-url

The URL of the new spawned community.

Required. No default.

-parentFolder

The ID of the parent folder for the spawned community.

The parent folder ID of community template

-enabled

Is the new community enabled?

The enabled value of community template

One of true or false.

-description

Description text for the spawned community.

The description of the community template

-membership

Membership request level for the spawned community.

Membership request level of community template.

-pageTemplate

The ID of the page template for the spawned community.

The page template ID of community template.

-style

The ID of the style for the spawned community.

The style ID of community template.

-gearTemplate

The ID of the gear template for the spawned community.

The gear template ID of community template.

-customization

The customization level for the spawned community.

The customization level of community template.

-access

The access control level for the spawned community.

Integer. The access control level of the community template.

-host

The hostname of the machine currently running you application server. If you do not specify this argument and the - port argument, then the

Defaults to localhost if no hostname is specified.

SpawnCommunity tool will start

and stop its own Nucleus service rather than using the currently running Dynamo.

-port

The port for the RMI server on the currently running Dynamo server.

8860

-cloneSharedGears

Should the spawned community clone shared gears, rather than refer to the original gears?

Boolean. Defaults to false.

33

ATG

Portal Administration Guide

µ

Automating the Portal Creation Process

You can combine an ATG Portal community template with the ATG Workflow engine to automate the process of creating new communities in your portal application. ATG Portal includes a CommunityProposal class, which embodies the basic properties of a proposed new community, as well as scenario and workflow actions that you can use to handle the process of approving the new community and automatically creating it from a community template.

To set up a community proposal workflow:

1. Assemble an application that includes the Portal.ppa module, which represents the Portal Process Automation. For information about application assembly and about ATG modules, see the ATG Programming Guide. Deploy and start the application you created according to the instructions from your application server manuals.

2. In the ATG Portal Administration interface, create a community template that you want to use as the basis of your new communities. You can have more than one community template. See the Creating Communities from Community Templates section in the Community Administration chapter.

3. In the ACC Workflow window, create a workflow to handle proposals to create new communities. See Creating a Workflow for Community Proposals.

4. In the ACC Scenarios window, create a scenario that listens for community proposal creation events and starts the community proposal workflow. See Creating a Scenario for Community Proposal Workflows.

5. Create a page or other code that initiates community proposals and creates community proposal creation events. See Creating a Community Proposal.

Community Proposals

A community proposal is represented as a Java object that can be handled in a workflow. Community proposals are maintained in a database and represented in a SQL repository named the Portal Process Repository. The Portal Process Repository has a Nucleus address of

/atg/portal/process/ProcessRepository.

Community Proposal Properties

ATG Portal includes a simple repository schema to support community proposal workflows. The Portal Process Repository defines a item descriptor named communityProposal. Each communityProposal repository item represents an individual community proposal. An item of type communityProposal includes the following properties:

Property

Description

community

The name of the community to be created

communityTemplate

The community template file. This file is created using the Portal Administration interface, as described in the Creating Communities from Community Templates section in the Community Administration chapter.

34

ATG

Portal Administration Guide

µ

creationDate

A

property automatically calculated from the current time when the

community proposal is created.

creator

The user who created the community proposal. This property is a user profile maintained in the Profile Repository.

id

A string ID for the community proposal.

lastModified

A property automatically calculated from the current time when the

community proposal is modified.

name

The name of the community proposal.

url

The URL segment for the new community.

version

An integer for the version number of the community proposal.

You can customize the community proposal to include other properties. To do so, you need to:

1. Modify the database schema for the Portal Process Repository. The SQL scripts that define this database schema are located at

<ATG2007.1dir>/Portal/ppa/sql/install.

2. Modify the repository definition file for the Portal Process Repository. This definition file is located at

<ATG2007.1dir>/Portal/ppa/config/atg/portal/process/ppa.xml.

3. Create a new community proposal Java class that implements the

atg.portal.process.CommunityProposal interface, adding methods to handle

your new properties.

Creating a Workflow for Community Proposals

Use the Workflow window of the ATG Control Center to create a workflow to handle proposals to create new communities. For more information about workflows in general, see the Creating and Configuring Workflows chapter in the ATG Personalization Programming Guide and the Using Workflows chapter in the ATG Personalization Guide for Business Users.

If you use ATG with the Portal.ppa module, then the ACC Workflow window includes a category named Community Proposal. Create your workflows in this window. The Portal.ppa module makes all the properties of a community proposal available in the Workflow editor.

A simple community proposal workflow might look like this:

35

ATG

Portal Administration Guide

µ

ATG Portal Administration Guide µ This simple workflow has the following elements: 1. The examine task

This simple workflow has the following elements:

1. The examine task calls for a worker to examine the community proposal. The result can be either approve or reject. If the community proposal is approved, then:

2. A new community is created, using the communityTemplate, name, and url properties specified in the community proposal. See Community Proposal Properties for a complete list of the properties of a community proposal.

3. The creator of the community proposal is assigned the role of leader for the new community.

4. The community specified by the community proposal is enabled (made active).

Create Community from Template Action

A Community Proposal workflow or scenario can make use of the Create Community from Template action. This action triggers the creation of a portal community. It takes the following input from the

CommunityProposal object:

Action Field

CommunityProposal Property

Community Template

communityTemplate

Community Name

name

Web Friendly URL

url

In addition, the Create Community from Template action takes the following input:

Action Field

Description

Community folder

Which community folder should this community be created in?

36

ATG

Portal Administration Guide

µ

Clone shared gears

Should this community get its own copy of its gear, or share an instance of the gear with the template?

Assign Community Role Action

A Community Proposal workflow or scenario can make use of the Assign Community Role action. This

action assigns roles in the community to designated users. It takes the following input:

Action Field

Description

Community id

The ID of the community in which you want to assign roles.

User id

The ID of the user to whom you want to assign a role.

Role Name

The name of the role you want to assign to the user.

Creating a Scenario for Community Proposal Workflows

Use the Scenarios window of the ATG Control Center to create a scenario that listens for community proposal creation events and starts the community proposal workflow.

A simple scenario to start a workflow might look like this:

A simple scenario to start a workflow might look like this: The scenario starts with the

The scenario starts with the creation of a community proposal. The scenario listens for

CommunityProposalMessages. A CommunityProposalMessage includes the CommunityProposal as a

property. Given the CommunityProposalMessage, the scenario starts a workflow, assigning the id property of the CommunityProposal as the subject ID of the workflow.

Creating a Community Proposal

ATG Portal includes a Nucleus component, /atg/portal/process/CommunityProposalHome, that can be used to create, edit, and delete community proposals. It includes getItem, createItem, addItem, and removeItem methods that work on CommunityProposal objects. The

CommunityProposalHome.addItem method creates a CommunityProposalMessage, which can be

37

ATG

Portal Administration Guide

µ

used by scenarios or other components as a starting point for creating new communities based on the

CommunityProposal object.

You can use the CommunityProposalHome component as a basis for form handlers, portlets, JSP pages or other interfaces that allow users to create, edit, and delete community proposals.

The following example creates a CommunityProposal, setting its name, url, and creator properties to

joe:

import javax.servlet.http.* import atg.portal.process.* import atg.userdirectory.* import atg.userprofiling.*

CommunityProposalHome home = (CommunityProposalHome)request.resolveName ("/atg/portal/process/CommunityProposalHome"); CommunityProposal cp = home.createItem(); cp.setName("joe"); cp.setUrl("joe"); UserDirectory ud = (UserDirectory) request.resolveName("/atg/userprofiling/ProfileUserDirectory"); Profile profile = (Profile)request.resolveName("/atg/userprofiling/Profile"); User user = ud.findUserByPrimaryKey(profile.getRepositoryId()); System.out.println("user = " + user); cp.setCreator(user); home.addItem(cp);

You could create a form page for creating community proposals that allows users to input the properties of the proposal.

Working with Community Membership

The Community Leader handles community membership tasks from the Community Administration Pages, including:

Adding a Member to a Community

Approving or Declining Membership Requests

Enabling Membership Request E-mail Notification

Assigning a Community Leader Role to a Member

Adding a Guest to a Community

Creating New Portal Users

Searching for Members in an LDAP Repository

38

ATG

Portal Administration Guide

µ

Adding a Member to a Community

Community membership can be assigned automatically. For more information on automatic membership, refer to the Community Membership section in this chapter. You can assign membership manually from the Community Users page of the Community Administration.

1. Log in to the Community Administration.

2. Click the Community Users tab.

The Community Members page opens.

3. Click add individuals.

The Add / Remove Individual Member page opens.

4. Use the search form to locate the individual you want to add to the community.

5. Check the box next to the new member’s name and click Add Selected.

The individual is now a community member.

You can also add all the members of an organization as members using the Member Organizations link:

1. Click Member Organizations in the side navigation panel.

2. Click add organizations.

3. Check the box next to the names of the organizations you want to add and click Add Selected.

Each of the individuals in the organizations you selected is now a community member.

Approving or Declining Membership Requests

If your portal uses the manual approval membership policy (Allow requests for membership and notify Community Leaders on the Community Settings page), then membership requests will be sent to the Approve/Decline Membership Requests page. The Community Leader uses this page to either approve or decline membership requests.

1. Log in to the Community Administration Pages.

2. Click the Community Users tab.

The Community Members page opens.

3. Click membership-request.

A page listing all pending membership requests appears. Each membership request shows the name and e-mail address of the person requesting membership.

4. For each person requesting membership, click later, approve or decline, then click Update. You can also select all pending requests at once by clicking one of the all later, approve all, or decline all links.

Enabling Membership Request E-mail Notification

The Portal Administrator can enable e-mail notification about membership requests. With this functionality enabled, members would receive an e-mail notifying them when their membership request

39

ATG

Portal Administration Guide

µ

is either approved or declined. You can do this by creating a Scenario based on the Membership Approved and Membership Declined events, which are generated when the Community Leader accepts or declines a membership request.

If you only need a simple e-mail notification, you can use the ATG Control Center to enable membership requests by e-mail, using the following procedure:

1. Open the ATG Control Center.

2. Select Pages and Components, followed by Components by Path.

3. Navigate to the /atg/portal/admin/CommunityPrincipalFormHandler.

4. Select the sendUserEmail property and set the value to true. Note that by default this property is set to point to the sendUserEmail property in /atg/portal/framework/Configuration, so you could also set this property in the

Configuration component.

5. Specify text strings for the requestEmailSubject, preMessage, postAcceptedMessage, and postDeclinedMessage properties.

The requestEmailSubject string appears in the e-mail’s Subject line; the preMessage string appears before the community name, the postAcceptedMessage string appears after the community name when the membership request is accepted; and the postDeclinedMessage appears after the community name when the membership request is declined. For example, when these properties are concatenated and the community name is included, the message might read: “Your membership request for the Tennis community has been approved.”

6. Make sure the emailer and emailSenderAddress properties are set properly.

7. Click Save.

Assigning a Community Leader Role to a Member

Community Leaders are responsible for assisting the Portal Administrator in membership and administration issues within a community. Portal Administrators and Community Leaders can assign the Community Leader role.

1. Log in to the Community Administration and click the Community Users tab.

2. Click the Leaders link in the side navigation bar.

The Leaders Page opens.

3. Click the add individuals link in the side navigation panel.

4. The Add / Remove Individual Leader page opens.

5. Use the search form to locate the individual to whom you want to assign a Community Leader role.

6. Check the box next to the new leader’s name and click Add Selected.

The individual is now a Community Leader.

You can also add all the members of an organization as Community Leaders using the Leader Organizations link:

40

ATG

Portal Administration Guide

µ

1. Click Leader Organizations in the side navigation panel.

2. Click add organizations.

3. Check the box next to the names of the organizations you want to add and click Add Selected.

Each of the individuals in the organizations you selected is now a Community Leader.

Adding a Guest to a Community

You can assign the Guest role to any registered user.

1. Log in to the Community Administration and click on the Community Users tab.

2. Click the Guests link in the side navigation bar.

The Guests page opens.

3. Click the add individuals link in the side navigation panel.

A page listing all community guests opens.

4. Use the search form to locate the individual you want to add to the community.

5. Check the box next to the new guest’s name and click Add Selected.

The individual is now a Community Guest.

You can also add all the members of an organization as members using the Guest Organizations link:

1. Click Guest Organizations in the side navigation panel.

2. Click add organizations.

3. Check the box next to the names of the organizations you want to add and click Add Selected.

Each of the individuals in the organizations you selected is now a community guest.

Creating New Portal Users

You can add new users to the Profile Repository using the Community Administration Pages.

1. Log in to the Community Administration Pages.

2. Click the Community Users tab.

The Community Members page opens.

3. Click create user in the side navigation panel.

The Create New Portal User page opens. Enter the profile information for the new user. Note that fields marked with an asterisk are required properties. Click Done to create a new user profile. You can then use the Community Users tab to assign roles to this user.

41

ATG

Portal Administration Guide

µ

Searching for Members in an LDAP Repository

If your user profiles are maintained in an LDAP profile repository, you need to configure ATG Portal to use

a different search form handler:

1. Change the Java class of the /atg/portal/admin/SearchUsers component to

atg.portal.admin.ldap.LDAPSearchUsersFormHandler.

2. Set the properties of this component to use the LDAP repository and its profile properties:

# /atg/portal/admin/SearchUsers $class=atg.portal.admin.ldap.LDAPSearchUsersFormHandler emailPropertyName=email firstNamePropertyName=firstName lastNamePropertyName=lastName loginPropertyName=login ldapRepository=/atg/adapter/ldap/LDAPRepository

42

ATG

Portal Administration Guide

µ

5 Portal Administration

The Portal Administrator is responsible for the content, appearance, and functionality of the portal, its communities, and pages. The Portal Administrator is also responsible for updating and maintaining the components of the portal site. As the Portal Administrator, you can control these settings using the Portal Administration Pages in the Portal Application Framework.

Manifest Files

The various gear components and style elements that make up the portal are added to the portal repository using manifest files. A manifest file is an XML file containing descriptions of one or more portal components, as well as links to any necessary resource files for those components. The component descriptions themselves can vary greatly, depending on the types of components they describe. Gear descriptions contain XML describing the size, shape, content, repository and functionality of the gear component. Layout descriptions contain XML describing the placement of the various gears in the portal. Color palette descriptions contain XML describing the various colors present in the page background and text of the portal.

You must import a manifest file into the portal repository before you can use the gears or style elements that it describes. To update a component in a repository, import a manifest file using the same component name as the existing setting. The new information overwrites the existing component description.

You can add component descriptions as a group by including them within the same manifest. When you upload a manifest to the Portal Administration Pages, only those components that match the type expected by the current administration page are added to the repository. For example, if you import a manifest from the Page Templates page, only page templates are added to the repository, even if the manifest contains descriptions of other components. Manifest files are discussed in depth in the Creating a Custom Portal chapter of the ATG Portal Development Guide.

You can see examples of gear manifest files in the module directory for each baseline gear included in ATG Portal. For example, the manifest file for the Calendar Gear is:

<ATG2007.1dir>/Portal/calendar/calendar-manifest.xml

You can see examples of manifests for style elements in:

<ATG2007.1dir>/Portal/paf/starter-portal/paf-dar/portal/templates

43

5

-

Portal

Administration

ATG

Portal Administration Guide

µ

We recommend that you save your manifest files after you have imported them into the PAF as they simplify the process of upgrading gears or moving them to another portal.

Style Administration

The Community Leader specifies the style elements that determine the appearance of community pages, including page templates, stylesheets, and gear title templates, for a community from the Community Settings page in the Community Administration Pages. Each setting has a unique name that you use to identify the style element. You can preview a page to see how your settings would look to a visitor to your site. The Portal Administrator makes these style elements available by uploading their manifest files from the Styles tab in the Portal Administration.

Page Templates

You can specify banners and other site wide graphics using page templates. Refer to Page Templates and Branding for more information on using page templates.

Adding Page Templates to the PAF

After you have created a page template manifest file, as described in the Creating a Custom Portal chapter of the ATG Portal Development Guide, you can add the manifest file to the PAF to make the new page template available to Community Leaders.

1. On the Portal Administration Home Page, click on the Styles tab.

The Page Templates page opens.

2. Enter the location of the page template manifest file in the text field, or use the Browse button to locate the file, then click Upload.

The page template is added to the list of available page templates on the page. You can use any of the listed page templates to design your portal pages.

Layout Templates

Layout templates let you specify the layout of your gears on the portal page. For example, you might choose to have all of your gears appear in two columns down the page, or you might choose to have your gears appear in three columns. Layout becomes very important when you are trying to arrange gears of different sizes and shapes for maximum usability and aesthetic value. The PAF installs with a set of four default layouts for your use. You can create your own layouts or edit the existing ones to fit the needs of your communities and portals. You can test the appearance of a layout template by applying it to a community and using the view link to view its effect on that community’s pages. For a listing of the default layout templates, refer to the Page Templates and Branding section of the Portal Configuration chapter of this guide.

44

5

-

Portal

Administration

ATG

Portal Administration Guide

µ

Adding Layout Templates to the PAF

After you have created a layout template manifest file, as described in the Creating a Custom Portal chapter of the ATG Portal Development Guide, you can add the manifest file to the PAF to make the new layout template available to Community Leaders.