atg portal administration guide - product version: 9 · portal.war paf the default portal in...

Version 9.4

Portal Administration Guide

Oracle ATG

One Main Street

Cambridge, MA 02142

USA

ATG Portal Administration Guide

Product version: 9.4

Release date: 10-31-11

Document identifier: PortalAdministrationGuide1307251603

Copyright © 1997, 2011 Oracle and/or its affiliates. All rights reserved.

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are

protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy,

reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any

means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please

report them to us in writing. If this software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of

the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT RIGHTS

Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial

computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific

supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and

license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the

additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle America, Inc., 500 Oracle

Parkway, Redwood City, CA 94065.

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended

for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or

hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures

to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in

dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are

trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or

registered trademarks of Advanced Micro Devices. UNIX is a registered trademark licensed through X/Open Company, Ltd.

This software or hardware and documentation may provide access to or information on content, products, and services from third parties.

Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party

content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to

your access to or use of third-party content, products, or services.

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/us/

corporate/accessibility/index.html.

Oracle customers have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/support/

contact.html or visit http://www.oracle.com/accessibility/support.html if you are hearing impaired.

ATG Portal Administration Guide iii

Table of 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Community Administration Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Community Settings Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Community Users Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Community Pages Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Community Gears Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Reset Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

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

Layout Template Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Gear Title Template Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Stylesheet Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Additional Branding Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Creating Style Element Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Localizing a Portal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Configuring E-mail Templates for Alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Portal and the Global Scenario Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

4. Community Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Individual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Community Folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Creating Community Folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Deleting Community Folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Reserved Community Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

iv ATG Portal Administration Guide

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Adding Gears to a Community Portal Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Viewing a Community Portal Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Deleting a Community Portal Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Creating Communities from Community Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Using the Community Templates User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Using the SpawnCommunity Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Automating the Portal Creation Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Community Proposals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Creating a Workflow for Community Proposals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Creating a Scenario for Community Proposal Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Creating a Community Proposal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Working with Community Membership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Adding a Member to a Community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Approving or Declining Membership Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Enabling Membership Request E-mail Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Assigning a Community Leader Role to a Member . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Adding a Guest to a Community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Creating New Portal Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Searching for Members in an LDAP Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

5. Portal Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Manifest Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Style Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Page Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Adding Page Templates to the PAF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Layout Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Adding Layout Templates to the PAF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Gear Title Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Adding Gear Title Templates to the PAF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Color Palettes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Adding Color Palettes to the PAF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Stylesheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Adding Stylesheets to the PAF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Gear Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Gear Folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

ATG Portal Administration Guide v

Gear Configuration Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Gear Installation Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Gear Instance Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Gear Parameter Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Adding Gears to the PAF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Deleting a Gear from the PAF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Sharing Gears in the PAF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Configuring Alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Creating New Administrative or Framework Alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Configuring an Alert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Deleting an Alert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Customization Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

6. Using Scenarios with ATG Portal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Using Portal Attributes in a Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Displaying a Gear in a Slot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Creating a Slot to Display a Gear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Creating Scenarios to Display Gears in Slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Portal Scenario Events and Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Preconfigured Portal Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

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

8. Baseline Gear Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Baseline Gears Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Configuring Baseline Gears . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Alerts Gear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Bookmarks Gear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Calendar Gear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Community Members Gear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Discussion Gear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Document Exchange Gear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Favorite Communities Gear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

HTML Content Gear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Login Gear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Outlook Gear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Poll Gear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Quicklinks Gear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Repository Search Gear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Repository View Gear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Targeted Content (Slot) Gear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Web Services Client Gear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

XML-Feed Gear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

XML Protocol Gear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

vi ATG Portal Administration Guide

1 Getting Started 1

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.

For information on supported operating systems, application servers, and databases for ATG Portal, see the

Supported Environments article on the My Oracle Support Web site (https://support.oracle.com). To

locate the article, search for “ATG Commerce Supported Environments” on the Knowledge tab.

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.

2 1 Getting Started

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 Archive Module Description

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

Poll poll

1 Getting Started 3

Gear Name Module Name

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.

4 1 Getting Started

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 (page 4)

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 (page 19) chapter.

2 Administration Pages 5

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 (page 5)

Community Administration Pages (page 8)

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 (page 6)

• Gears Tab (page 6)

• Styles Tab (page 7)

• Alerts Tab (page 7)

6 2 Administration Pages

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:

For more information on communities, refer to the Community Administration Pages (page 8) section in this

chapter and the Community Administration (page 19) 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:


For more information on baseline gears, the set of prefabricated gears provided with the PAF, refer to Gear

Administration (page 46). 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.

• 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 (page

13) 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 (page 44) 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 (page 45) in the Style Administration section of the Portal Administration chapter and to Gear

Title Template Files (page 14) in the Page Templates and Branding section of the Portal Configuration

chapter.

• 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 (page 45) 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 (page 46) 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:

You can create new administrative or framework alerts or configure existing alerts using the Portal

Administration. See Configuring Alerts (page 49) in the Portal Administration (page 43) 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 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 (page 9)

• Community Users Tab (page 9)

• Community Pages Tab (page 9)

• Community Gears Tab (page 9)

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.

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.

3 Portal Configuration 11

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 (page 11)

Configuring Your Repositories (page 11)

Business Rules (page 13)

Page Templates and Branding (page 13)

Localizing a Portal (page 16)

Configuring E-mail Templates for Alerts (page 17)

Portal and the Global Scenario Server (page 17)

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

12 3 Portal Configuration

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.

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 <ATG9dir>/Portal/paf/framework/

liveconfig/atg/portal/framework/portalRepository.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 (page 12) 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:


<ATG9dir>/Portal/paf/config/atg/userprofiling/userProfile.xml

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:

<ATG9dir>/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:

<ATG9dir>/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 <ATG9dir>/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 <ATG9dir>/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 (page 44) 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.


Shared and Full Page Template

The shared and full page template (<ATG9dir>/Portal/paf/starter-portal/paf-dar/portal/

templates/page/html/shared.jsp and <ATG9dir>/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 Template Files

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 <ATG9dir>/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

<ATG9dir>/Portal/paf/starter-portal/paf-dar/portal/templates/titlebar folder.

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 <ATG9dir>/Portal/paf/starter-portal/paf-dar/portal/

templates/style/css. See the Style Administration (page 44) 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 <ATG9dir>/Portal/paf/starter-portal/paf-dar/

portal/userprofiling

Logout logout.jsp <ATG9dir>/Portal/paf/starter-portal/paf-dar/


Registration register.jsp <ATG9dir>/Portal/paf/starter-portal/paf-dar/


Error error.jsp <ATG9dir>/Portal/paf/starter-portal/paf-dar/

portal

Access Denied accessDenied.jsp <ATG9dir>/Portal/paf/starter-portal/paf-dar/

portal/access

Community Offline offline.jsp <ATG9dir>/Portal/paf/starter-portal/paf-dar/

portal/access

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 <ATG9dir>/Portal/paf/starter-portal/paf-dar/portal. Once you have created the new style

element files, refer to Style Administration (page 44) 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 <ATG9dir> directory, create the following directory branch:

<ATG9dir>/home/locallib/atg/portal/framework

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

<ATG9dir>/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:

# 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-8charset=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.

4 Community Administration 19

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

20 4 Community Administration

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.

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 (page 21) section below.

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 <ATG9dir>/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.


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.

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.

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 (page 24)

• Limiting a Community’s Access to Gears (page 26)

• Editing a Community (page 27)

• Disabling a Community (page 27)

• Deleting a Community (page 27)

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

• Editing a Community Portal Page (page 28)

• Adding a Community Portal Page (page 28)

• Adding Gears to a Community Portal Page (page 29)

• Viewing a Community Portal Page (page 29)

• Deleting a Community Portal Page (page 30)

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 (page 37) 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.

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 (page 27) 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 (page 30)

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 (page 48) 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 (page 26) 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.


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:


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.

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.


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:

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.

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 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 (page 29) 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.

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 (page 28) 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 (page 48) in the Portal Administration (page

43) chapter. Next, a Community Leader must add an instance of the gear to the community. See Making

Gears Available to a Community (page 25) 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 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 (page 33) 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.

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 <ATG9dir>/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.

-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?

One of true or false.

The enabled value of

community template

-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.


Argument Description Default Value

-host The hostname of the machine

currently running you application

server. If you do not specify

this argument and the -

port argument, then the

SpawnCommunity tool will start

and stop its own Nucleus service

rather than using the currently

running Dynamo.

Defaults to localhost if no

hostname is specified.

-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.

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 (page 35).

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 (page 36).

5. Create a page or other code that initiates community proposals and creates community proposal creation

events. See Creating a Community Proposal (page 36).


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 (page 30) section in the Community Administration chapter.

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 <ATG9dir>/Portal/ppa/sql/install.

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

<ATG9dir>/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:

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 (page 34) 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?

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:

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 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 (page 37)

• Approving or Declining Membership Requests (page 38)

• Enabling Membership Request E-mail Notification (page 38)

• Assigning a Community Leader Role to a Member (page 39)

• Adding a Guest to a Community (page 39)

• Creating New Portal Users (page 40)

• Searching for Members in an LDAP Repository (page 40)

Adding a Member to a Community

Community membership can be assigned automatically. For more information on automatic membership, refer

to the Community Membership (page 23) 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 AddSelected.

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 AddSelected.

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.



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 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:




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:

1. Click Leader Organizations in the side navigation panel.



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.



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.



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.

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

5 Portal Administration 43

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:

<ATG9dir>/Portal/calendar/calendar-manifest.xml

You can see examples of manifests for style elements in:

<ATG9dir>/Portal/paf/starter-portal/paf-dar/portal/templates

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.

44 5 Portal Administration

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 (page 13) 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 (page 13) section of the Portal Configuration chapter of this 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.

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



Click on the Layout Templates link in the side navigation panel.

2. Enter the location of the layout template manifest file in the text field, or use the Browse button to locate the


The layout template is added to the list of available layout templates on the page. You can use any of the

listed layouts to design your portal pages.

Gear Title Templates

Gear Title templates let you specify the formatting that appears around gears. Gear Title options include:

• Gear title bar

• Gear table formatting

For information on creating your own gear title templates, refer to the Customizing Portal Appearance section

of the Creating a Custom Portal chapter in the ATG Portal Development Guide. In addition, the standard gear

title templates are described in the Page Templates and Branding (page 13) section of the Portal Configuration

chapter of this guide.

Adding Gear Title Templates to the PAF

After you have created a gear title 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 gear title template

available to Community Leaders.

1. In the Portal Administration Pages, click on the Styles tab.


Click on the Gear Title Templates link in the side navigation panel.

2. Enter the location of the gear title template manifest file in the text field, or use the Browse button to locate

the file, then click Upload.

The gear title template is added to the list of available templates on the page. You can use any of the listed

templates to design your portal pages.

Color Palettes

The Color Palettes Page lets you set the colors and background images that appear in your portal. Color palette

options include:

• Background color

• Text color

• Active link color

• Visited link color

• Background image

For information on creating your own color palettes, refer to the Customizing Portal Appearance section of the

Creating a Custom Portal chapter in the ATG Portal Development Guide.


Adding Color Palettes to the PAF

After you have created a color palette 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 color palette available

to Community Leaders.

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

The Color Palettes page opens.

2. Enter the location of the color palette manifest file in the text field, or use the Browse button to locate the


The color palette is added to the list of available color palettes on the page. You can use any of the listed color

palettes to design your portal pages.

Stylesheets

The Stylesheets Page lets you apply cascading stylesheets to your portal pages. You can upload a stylesheet

manifest file that specifies a location for cascading stylesheets by providing a servlet context and a URL. For

information on creating your own stylesheet manifests, refer to the Customizing Portal Appearance section of the

Creating a Custom Portal chapter in the ATG Portal Development Guide.

Adding Stylesheets to the PAF

After you have created a cascading stylesheet and a stylesheet 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 stylesheet available to Community Leaders.

To add a stylesheet manifest file to your PAF:

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

The Stylesheets page opens.

2. Enter the location of the stylesheet manifest file in the text field, or use the Browse button to locate the file,

then click Upload.

The stylesheet is added to the list of available stylesheets on the page. You can use any of the listed

stylesheets to design your portal pages.

Gear Administration

The most technical task of the Portal Administrator is gear administration. The gears are the site components

that provide content and functionality. The content and functionality provided by the gear can vary greatly

depending on the gear itself. For more information on gears, and how to create, package, and deploy them,

refer to the ATG Portal Development Guide. You can customize the functionality of each gear at the portal and

community level, to provide your visitors with the functionality that best suits their needs.

Portal Administrators should make sure that the assets of the loaded layout templates, styles, color palettes, and

gears are loaded into the application server. For example, if the gear is contained within a J2EE application, then


the Portal Administrators need to configure the application server so that it registers the J2EE application before

the manifest is loaded. For more information, see the ATG Programming Guide.

Gear Folders

Gears are organized into gear folders. Gear folders let you make gears available to communities in logical

groups. To create a new gear folder:

1. In the Portal Administration Pages, click the Gears tab.

The Available Gears page opens showing a list of gear folders and the gears they contain.

2. Click the New Gear Folder link in the side navigation panel.

3. Enter a name for the new gear folder and click Done.

Gear Configuration Types

Depending on how it was designed, a gear may be configurable from the Portal Administration Pages, the

Community Administration Pages, or both. In addition, you can configure any gear by editing the gear

parameters and reloading the gear manifest file. If the instructions in the Baseline Gear Administration (page

65) chapter do not specify the type of configuration, the instructions are for a gear instance configuration.

Gear Installation Configuration

Some gears are configurable only by Portal Administrators from the Portal Administration Pages. When

you configure one of these gears, the changes take effect across all of your communities. This is called a

gearinstallationconfiguration; changes made here apply to all instances of the gear, regardless of community. For

example, when you set the source feed for an XML-Feed Gear, that source is used in all instances of that gear in

all communities.

Gear Instance Configuration

Some gears are configurable by Community Leaders from the Community Administration Pages. When

you configure one of these gears, the changes take effect only in the current community. This is called a

gearinstanceconfiguration; changes made here apply only to the current instance of the gear, and do not appear

in any other community. For example, when you configure a Discussion Gear for the Tennis Community, those

changes apply only to the Tennis Community. It is often helpful to give a gear instance a name that helps you

distinguish it from the installation name of the gear, for example, Tennis Discussions for an instance of the

Discussion Gear.

Gear Parameter Configuration

You can also configure a gear by altering its parameters in the gear manifest and importing the manifest again.

For more information on editing gear manifest files, refer to the ATG Portal Development Guide.


Adding Gears to the PAF

Once a gear has been created and its manifest file written, as described in the ATG Portal Development Guide, you

can use the manifest file to add the gear to your portal.


The Available Gears page opens, showing a list of gear folders and the gears they contain.

2. Click the New Gear link in the side navigation panel.

The New Gear page opens.

3. Select a gear folder. Alternatively, you can click the New Gear Folder link to create a new folder.

4. Enter the location of the gear manifest file in the Upload gear manifest file field, or use the Browse button

to locate the file.

5. Click Upload.

The gear is added to list of available gears (in the folder you specified) on the Available Gears page. To add

the new gear to your portal pages, first make the gear folder available to the community, using the gear

folders link for the community on the Available Communities page in the Portal Administration. Then,

make an instance of the gear available, using the Select New Gears option on the Community Gears tab in

the Community Administration. See Making Gears Available to a Community (page 25) in the Community

Administration chapter.

Deleting a Gear from the PAF

The following procedure removes a gear from a portal.


The Available Gears page opens.

2. Locate the gear you want to remove and click its delete link.

3. Confirm the deletion.

The gear is no longer available to the PAF. Deleting a gear deletes all instances of the gear on all community

pages.

Sharing Gears in the PAF

You can share an instance of a gear across multiple communities. For example, if you create an instance of the

Poll Gear asking a question that applies to many communities within a company, you can share that instance

of the Poll Gear across these communities rather than creating many duplicate instances of the same gear.

Although a shared gear instance can appear in many communities, it is only configurable from the community

in which it was created.


Shared gears are configured in the Community Administration Pages. Once a gear is shared, you cannot unshare

it. To share a gear:

1. In the Community Administration Pages for the community where the gear was created, click the Community

Gears tab in the top navigation bar.

The Current Gear Instances page opens.

2. In the list of available gears, click the Configure link for the gear you want to set as a shared gear.

The Configure Gear basics page opens.

3. Give the gear instance a name and a description.

4. Under the Sharing heading, check the Allow this gear to be shared with other communities check box.

5. Finish configuring the gear and click Update.

This instance of the gear is now available to other communities from the Select Shared Gears page of the

Community Gears tab in the Community Administration. Its instance name appears listed beneath the

community in which it was created.

Configuring Alerts

ATG Portal includes alerts, which are notifications that originate from a gear event, are filtered and targeted

by ATG Scenario Personalization, and are presented to their target audience. Alerts can be presented through

different channels, including the Alert Gear, which can be included in portal pages, or by e-mail sent to the

portal member.

Most alerts in ATG Portal are gear alerts, which are generated by particular gears in the portal application. The

Adding Gear Alerts chapter of the ATG Portal Development Guide describes how to create a new gear alert. The

Alerts tab in the Portal Administration does not affect gear alerts.

In addition, ATG Portal includes administrative alerts and framework alerts. Administrative alerts are messages

that are generated from the Portal Administration Pages, while framework alerts are generated by the PAF. You

can use the Alerts tab in the Portal Administration to manage and create administrative and framework alerts.

You should not need to create new administrative or framework alerts unless you have extended the Portal

Administration or the PAF.

Creating New Administrative or Framework Alerts

Once you have created the alert, you can add it to the PAF using the Alerts tab in the Portal Administration. To

add a new alert:

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

2. Click either New Administrative Alert or New Framework Alert on the side navigation bar.

3. Enter the following information about the new alert and click Save:

Message Name A name that identifies the message. This is not a unique identifier.


Message Type The message type is the full package name of the message type, for example:

atg.portal.messaging.OrangeAlert

The message type is a unique identifier.

Resource Bundle The full package name of the resource bundle used by the message type, for

example:

atg.portal.messaging.MyMessageResources

Select a radio button to indicate how this alert can be configured:

User alerts not allowedAlerts allowed, but not user-configurableAlerts allowed, configurable by user

Configuring an Alert

You can configure existing administrative or framework alerts to a limited extent. To configure an alert:


2. Click either New Administrative Alert or New Framework Alert on the side navigation bar.

3. Click the configure link for the message name you want to configure.

4. Modify either the resource bundle pathname or the configurability setting for the alert and click Save.

Deleting an Alert

You can delete an existing administrative or framework alert in the Portal Administration. To delete an alert:


2. Click either Administrative Alerts or Framework Alerts on the side navigation bar.

3. Click the delete link for the message name you want to configure.

4. When the confirmation message appears, click Yes, Delete.

Customization Administration

Depending on the permissions set by the Community Leader, portal users can customize the appearance and

content of their portal pages. These permissions are configurable under the Customization heading on the

Community Settings page of the Community Administration.

If you allow community customization, changes made by the Community Leader do not automatically appear

on individual user pages. The following settings are available


Allow users to customize, add and delete

pages

This setting gives users the ability to customize their pages,

as well as the ability to create and remove additional pages

within the community. This setting provides the broadest

customization options.

Allow users to customize pages This setting gives users the ability to customize their pages.

The ability to create new pages is limited to the Community

Leader.

Do not allow customization This setting prevents users from customizing their pages.

The Community Leader must make any changes in portal

appearance or design.

6 Using Scenarios with ATG Portal 53

6 Using Scenarios with ATG Portal

ATG Scenario Personalization provides advanced targeting features that companies can use to plan and manage

long term personalization and customer relationships. You can use scenarios to enhance your users’ experience

in your portal application and to gather information about how your users are using your portal application.

Using Portal Attributes in a Scenario

You can easily set up scenarios that key off of portal attributes. The Portal Servlet Request object is accessible in

the Scenario editor, enabling scenarios based on any of its attributes.

Displaying a Gear in a Slot

ATG Scenarios can employ slots to display targeted variable content on a page. You can learn more about slots

in the Creating Scenarios chapter of the ATG Personalization Guide for Business Users and the Using Slots chapter in

54 6 Using Scenarios with ATG Portal

the ATG Personalization Programming Guide. One of the ATG Portal baseline gears, the Slot Gear, lets you display

a slot’s content in a portal page. This section describes how, in an ATG Portal application, you can use a slot to

display different gears based on targeting rules.

Creating a Slot to Display a Gear

The first step in using a slot to display gears is creating the slot component.

1. In the ACC, navigate to Scenarios > Slots.

2. Click the New Slot button.

3. Use the Create New Slot wizard, providing a name for the slot. Click Next.

4. In the Specify Slot Content Type dialog, select Repository Item as the type of items stored in the slot. Click

Next.

5. In the Specify Slot Content Source field, select the Portal Repository as the content source and Gear as the

content type. Click Next.

6. Use the Specify Slot Options dialog to configure the slot. See the Using Slots chapter in the ATG Personalization

Programming Guide for more information about configuring slot options.

Creating Scenarios to Display Gears in Slots

After you create your slot component, you can use ATG Scenarios to determine under what circumstances a

gear will be displayed in a slot. The Creating Scenarios chapter in the ATG Personalization Guide for Business Users

provides information about how to create a scenario.

For example, you could create a scenario that adds a poll to a portal user’s home page upon login, and removes

the poll after the user has voted in the poll. To do this, create a new scenario with the Logs in event followed by

the Add items to slot action segment, and the Poll vote event followed by the Remove items from slot action

segment:

The following JSP example shows how you might use a slot to render a gear. It assumes you’ve created a slot

named /com/acme/slots/MyGearSlot. The TargetingFirst servlet bean is used to display the appropriate

gear.

<%@ page import="atg.portal.servlet.*,atg.portal.framework.*" %><%@ taglib uri="/paf-taglib" prefix="paf" %>


<%@ taglib uri="/dsp" prefix="dsp" %>

<dsp:page>

<dsp:droplet name="/atg/targeting/TargetingFirst"> <dsp:param name="targeter" bean="/com/acme/slots/MyGearSlot"/> <dsp:oparam name="output">

<dsp:getvalueof id="gearId" param="element.repositoryId" idtype="java.lang.String">

<% //Obtain request/response PortalServletResponse portalServletResponse = (PortalServletResponse)request.getAttribute(Attribute.PORTALSERVLETRESPONSE); PortalServletRequest portalServletRequest = (PortalServletRequest)request.getAttribute(Attribute.PORTALSERVLETREQUEST);

Portal portal = portalServletRequest.getPortal(); if(portal != null) { Gear gear = portal.getGearById(gearId);

if(gear != null) { //Create Gear Context GearContextImpl gearContext = new GearContextImpl((GearContext)portalServletRequest); gearContext.setGear(gear); gearContext.setGearMode(GearMode.CONTENT);

//Dispatch Gear RequestDispatcher dispatcher = portalServletRequest.getRequestDispatcher(gearContext); if(dispatcher != null) dispatcher.include(request,response); } }%>

</dsp:getvalueof>

</dsp:oparam></dsp:droplet>

</dsp:page>

Portal Scenario Events and Actions

ATG Portal is configured with the following scenario events, which can serve as triggers for scenario actions:

Calendar Event Created

Calendar Event Deleted

Calendar Event Updated

Calendar Event Viewed


Community Page Viewed

Document Created

Document Deleted

Document Updated

Document Viewed

Favorite Community Added

Favorite Community Removed

Full URL Changed

Gear Added to Community

Gear Added to Page

Gear Removed from Community

Gear Removed from Page

Membership Accepted

Membership Declined

Membership Request

Membership Unsubscribe

New Forum Created

Poll Vote

Registers

ATG Portal is configured with the following community- and gear-related scenario actions:

Send alert

Store Last downloaded Document

Store Last viewed Calendar Event

Create Community from Template

Assign Community Role

Preconfigured Portal Scenarios

ATG Portal includes the following already-configured scenarios:

Scenario Name Description

Discussions Send alerts to community members when a new discussion forum is created.

Gear Added Alert Send alerts to community leaders when a gear is added to the community.

Gear Removed Alert Send alerts to community users when a gear is removed from the

community.

Membership Request Send alerts to community leaders when a user requests to be made a

member of the community.

Page Gear Added Alert Send alerts to community members when a gear is added to a community

page.

Page Gear Removed Alert Send alerts to community members when a gear is removed from a

community page.

Portal Calendars Send alerts to community members when Calendar gear events are created,

updated, or deleted.


Scenario Name Description

Portal Usage Record community page views, document views, calendar event views, and

Poll gear votes in the appropriate dataset. See Using Scenario Recorders in

the ATG Personalization Programming Guide for more information about data

recording scenarios.

Profile Updates When a user updates his profile, send him an email to confirm.

Registration When a user registers, send an email to confirm.

Site Retention If a user goes 15 days without logging in, send a reminder email.

Track Portal Behavior Modify a user’s profile to track the number of times he publishes documents,

views documents, creates calendar events or views calendar events.

7 Portal Access Control 59

7 Portal Access Control

ATG Portal is subject to the security settings specified within the ATG Relationship Management Platform. PAF

security settings are handled primarily from the administrator interface, although additional tags and methods

are available to further maintain portal security from within individual gears and the PAF itself. For a more

detailed discussion of security within the ATG platform, refer to the Managing Access Control chapter in the

ATG Programming Guide and the Working with the Dynamo User Directory chapter in the ATG Personalization

Programming Guide.

J2EE Security

ATG Portal makes limited use of J2EE security features in the portal. It calls request.getUserPrincipal() and

uses the returned information, but makes no use of contextual security. Portal security is handled dynamically,

and is relative to the current community.

Community Security Administration

Each page in a community can be restricted according to access level, allowing some areas of a community to

be accessible to some users but not others. Community-level access supersedes page-level access, so looser

page level access control levels are ignored if the page’s community is more restrictive.

Beyond the page level, the security provided by the PAF security methods and tags can apply restrictions at the

gear level. For example, a particular page might be available to members of a community, but a gear on that

page might only be available to Community Leaders. Gears that a user does not have access to are not rendered

on the page.

ATG Portal contains options for community-specific and gear-specific security settings. You can specify

page security settings from the Community Access section of the Community Settings page of the Portal

Administration pages. You can specify gear security settings by editing the individual gear configuration.

If users attempt to access a community page for which they do not have access, one of two events takes place:

• If the user is not logged in, the user is directed to the login page. After authentication, the user is redirected to

the desired page.

• If the user is logged in, and does not have permission to view the page, the user is redirected to the “access

denied page.”

60 7 Portal Access Control

Gears will not function correctly if you try to access them directly in their servlet context (for example

http://hostname:port/gear/gearname/shared.jsp).

Setting Basic Access Levels for a Community

A Community Leader can set the access levels for the community using the Community Administration.

1. Click the Community Settings tab in the Community Administration.

2. Click Community Access in the side navigation bar.

3. Select one security level from the Basic Access page and click Update.

The following access levels are available:

Allow anyone, including Unregistered Users This is the most open level of security. Any visitor

can view the community pages without registering

or logging in.

Allow all Registered Users This setting requires that users register before

viewing the community pages. There are no

restrictions on who can or cannot register.

Allow Community Guests, Members, and Leaders This setting requires that the visitor have a defined

role within the community, but places no restriction

on what the community role must be.

Allow Community Members and Leaders This setting requires that the visitor have

Community Member or Community Leader status.

Allow Community Leaders only This setting is the most restrictive level of

community-based security. Only Community

Leaders and Portal Administrators have access to

the community.

Setting Advanced Access Controls for a Community

The basic access controls let you assign access to a community based on broad categories of roles in the

community, like Guest, Member, and Leader. The advanced access controls let you assign access with finer

granularity, allowing or denying access to particular organizations and even individuals among your portal’s

users. Note that advanced access is additive to the permissions granted by the basic access controls. For

example, if you allow access to all registered users with the basic access controls, and then allow access to

an organization using the advanced access controls, then all members of that organization will have access,

whether they are registered users or not.

To use the advanced access controls to set access for a particular individual:


2. Click Community Access in the side navigation bar to make the Advanced Access option visible.


3. Click Advanced Access in the side navigation bar.

The Configure Community Access page opens.

4. Select Search Users in the pulldown menu at step 1 of the Configure Community Access page and click find.

5. Enter a name to search by in the search form at step 2 of the Configure Community Access page and click

Search.

6. Select either the allow or deny button at step 3 of Configure Community Access page and click Update.

To use the advanced access controls to set access for a member organization:


2. Click Community Access in the side navigation bar.

3. Click Advanced Access in the side navigation bar.

The Configure Community Access page opens.

4. Select Member Organizations in the pulldown menu at step 1 of the Configure Community Access page and

click find.

All of the member organizations are displayed in step 3 of Configure Community Access page.

5. Optionally, you can limit the number of organizations displayed by entering a name to search by in the search

form at step 2 of the Configure Community Access page and clicking Filter.

6. Select either the Allow or Deny button at step 3 of Configure Community Access page and click Update.

Setting Community Access by Role

An ATG application allows you to assign roles to users. A role corresponds to specific functions that a person

can perform within an organization, such as “vice president” or “administrator.” You can use the Community

Administration interface to assign access based on roles, as well as based on organizations. This lets you

have gears or pages that are accessible to people in different organizations who have the same roles in their

organizations. For example, you might have a gear that can be accessed by users who have a budget making

role in their organization.

For more information about how roles work in ATG applications, see the Setting Up Visitor Profiles chapter in the

ATG Personalization Guide for Business Users or the Working with the Dynamo User Directory chapter in the ATG

Personalization Programming Guide.

Use the Community Administration interface to assign access based on roles:

1. From the Community Settings page for a community, click Community Access > Advanced Access.

2. In the Configure Community Access page, select All Roles from the pulldown menu in the page’s step 1, then

click the find button.

3. In the step 3 section of the Configure Community Access page, use the radio buttons to allow or deny access

to the community for any applicable roles. Click the Update button when you are done.


If you allow access for a particular role, then users with that role are allowed access unless another access rule

specifically denies access for them. If you deny access for a particular role, then users with that role are denied

access, even if another access rule would allow them access. If you do not specifically set allow or deny access

for a particular role, then that role is ignored for the purpose of determining access. In that case, access is

determined by a user’s organization or username.

Page and Gear Level Access Control

You can also use the Community Administration interface to set access controls for individual pages or gears in a

community. This works in basically the same way as setting access at the community level.

To set access controls for a page:

1. From the Community Pages page for a community, click Current Pages.

2. Click the access link for the page you want to configure access for.

3. In the Configure Access page, make a selection from the pulldown menu in the page’s step 1, then click the

find button.

4. In the step 3 section of the Configure Access page, use the radio buttons to allow or deny access to the page

for any applicable users, organizations, or roles. Click the Update button when you are done.

To set access controls for a gear:

1. From the Community Gears page for a community, click Current Gear Instances.

2. Click the Access link for the gear instance you want to configure access for.

3. In the Configure Access page, make a selection from the pulldown menu in the page’s step 1, then click the

find button.


4. In the step 3 section of the Configure Access page, use the radio buttons to allow or deny access to the

community for any applicable users, organizations, or roles. Click the Update button when you are done.

Predefined Secured Areas

Some areas in the PAF have built-in security. Any pages generated within the areas below by default require a

minimum level of security. In addition, you may wish to implement SSL security for the Portal Administration

interface. See the documentation for your application server for information about deploying Web applications

that use SSL.

• Portal Administration Pages:The Portal Administration, including all pages in the /portal/admin area,

manages portal-wide configuration settings, including the importation and configuration of gears. By default,

only users who have the Portal Administrator role are allowed access to this area.

• Community Administration Pages:The Community Administration, including all pages in the /portal/

settings area, manages community-specific configuration settings. By default, only Portal Administrators

and Community Leaders are allowed access to this area.

8 Baseline Gear Administration 65

8 Baseline Gear Administration

ATG Portal includes a number of baseline gears that provide basic gear functionality. You can configure the gears

to provide specific functionality for your communities.

Baseline Gears Overview

A standard installation of ATG Portal includes the following gears.

Alerts Gear

The Alerts Gear displays alert notifications generated by events occurring within the portal. For example, the

Alerts Gear might notify a visitor that a new document has been added to the Document Exchange Gear.

Bookmarks Gear

The Bookmarks Gear makes available a list of user-customizable bookmarks.

Calendar Gear

The Calendar Gear displays a monthly list of important events for the community. Events added to the Calendar

Gear are visible to all visitors of a community.

Community Members Gear

The Community Members Gear displays a list of the members of the community. The list is updated as

community membership changes.

Discussion Gear

The Discussion Gear lets users participate in threaded online discussions with other users in the community.

Registered users can create discussion boards as well as read, reply to, and post messages. Portal Administrators

and Community Leaders can moderate these forums and edit the discussion boards as necessary.

Document Exchange Gear

The Document Exchange Gear lets visitors interact with any document repository. Depending upon their

security permissions, visitors can upload, download, annotate, edit, and share documents with other registered

users in the portal community. Portal Administrators can use security permissions to maintain the integrity of

the document repository. ATG can also use the documents in the repository to create new dynamic content

within the PAF.

Favorite Communities Gear

The Favorite Communities Gear displays a list of the member’s favorite communities. Community Members

can individually configure their own list of favorite communities, or they can display a list of all the available

communities.

HTML Content Gear

66 8 Baseline Gear Administration

The HTML Content Gear retrieves the contents of the Web location, given its URL, the renders it as gear content.

The gear ensures that all the URIs in the Web content are properly rewritten so that the links shown in the gear

content point to the original Web server.

Login Gear

The Login Gear provides a secure interface for visitors to log in to the community. Once they are authenticated,

visitors assume their role within the community.

Outlook Gear

The Outlook Gear gives visitors access to their Microsoft Outlook account. Visitors can use this access to send

and receive e-mail from within the portal.

Poll Gear

The Poll Gear asks a single question, and presents a visitor with a set of responses. Visitors can respond to the

poll question, and view the results of the previous respondents.

Quicklinks Gear

The Quicklinks Gear provides a list of bookmarks for the community, created and customized by the Community

Leader.

Repository View Gear

The Repository View Gear can display information about repository items from any ATG repository.

Web Services Client Gear

The Web Services Client Gear enables portal visitors to access Web services made available on remote

computers. A Web service application can describe itself, publish this description to a directory, and be invoked

remotely over a network via Simple Object Access Protocol (SOAP). The Web Services Client Gear acts as a client

in Web service transactions. For example, the Web Services Client Gear might be used to access stock market

information and functionality made available as a Web Service by a financial content provider.

XML-Feed Gear

The XML-Feed gear acts as a content feed, providing information from an external source that displays within

your portal. Information fed through the XML-Feed Gear is not stored in any way.

Configuring Baseline Gears

You can configure gears within a community, or directly from the Portal Administration Pages. To configure a

gear, you must have a Portal Administrator or Community Leader role and be able to access the Gears tab of the

Portal Administration or the Community Gears tab of the Community Administration. This section includes the

following topics:

Alerts Gear (page 67)

Bookmarks Gear (page 68)

Calendar Gear (page 68)

Community Members Gear (page 69)

Discussion Gear (page 70)

Document Exchange Gear (page 71)

Favorite Communities Gear (page 74)


HTML Content Gear (page 74)

Login Gear (page 76)

Outlook Gear (page 76)

Poll Gear (page 77)

Quicklinks Gear (page 78)

Repository Search Gear (page 78)

Repository View Gear (page 79)

Targeted Content (Slot) Gear (page 81)

Web Services Client Gear (page 83)

XML-Feed Gear (page 85)

Alerts Gear

Module name: alert

The Alerts Gear displays alert notifications generated by events occurring within the portal. For example, the

Alerts Gear might notify a visitor that a new document has been added to the Document Exchange Gear.

Instance Configuration

To configure an instance of the Alerts Gear:

1. Enter the Community Administration and click the configure link for the Alert Gear instance.

2. In the configuration basics page, enter a gear name and description. Select sharing and Make visible to

options and click Done.

3. Click the additional configurations link. Set the display count parameter for this gear instance to specify

how many alerts display in the shared view of the gear.

4. Click the access parameters link. Specify which alerts are to be displayed, based on where they were

targeted by the Send Alert Scenario action. You can enable or disable the following alert categories:

aggregated community alerts

community alerts

role alerts

organization alerts

user alerts

5. Click Update.

Configuring the Alerts Gear Repository Module in ACC

You can use the ACC to control data removal for the Alerts Gear repository. Over time, as the actions of users

on your portal generate more and more alerts, the amount of data storage required by alerts increases. If

you do not configure data removal settings, you can potentially exceed your data storage capacity. For more

information on using the ACC, refer to the ATG Personalization Guide for Business Users.

To configure the Alerts Gear repository for data removal:




3. Open the /atg/portal/alert/AlertRepositoryAdmin component.

4. In the AlertRepositoryAdmin component, set the properties for data removal.

The properties and their options are listed in the table below.

5. Once you have set the data removal properties, click Start.

The component starts, using the settings you have specified.

AlertRepositoryAdmin Properties Description

expirationDate Specifies the date after which data is outdated and ready to be

deleted.

expirationDays Specifies the number of days after which data is outdated and

ready to be deleted. Use this property if you are going to run

the removal process as a recurring event.

schedule Specifies the interval at which the removal process runs. The

default setting for this property is one hour.

Bookmarks Gear

Module name: bookmarks

The Bookmarks Gear makes available a list of user-customizable bookmarks. Users can add bookmarks by

clicking the Edit button in the gear and entering URLs.


The Bookmarks Gear has only the usual basics to configure. To configure an instance of the Bookmarks Gear:

1. Enter the Community Administration and click the configure link for the gear instance.



Calendar Gear

Module name: calendar

The Calendar Gear displays a monthly list of important events for the community. An event added to the

Calendar Gear can be labeled private, in which case only the user who entered the event can view it, or public/

community, in which case the event is visible to all visitors of a community.


To configure an instance of the Calendar Gear:





3. Click the additional configurations link.

4. On the calendar parameters page, select basic or detailed for the calendar default event type. Detailed

events will prompt for name and address information for the event. Select a calendar year end. The calendar

will allow the creation of events only until the end of the year you specify.

5. Click the permissions link. This page governs who can create private and public events. By default, users with

the calWriter role can create only private events; users with the calAdmin role can create public or private

events. Set the Allow open access to create public and private events? field to true to permit anyone who

can use the Calendar gear instance to create a public or private event. Set the Allow open access to create

private events only? field to true to permit anyone who can use the Calendar gear instance to create a

private event.

See the Assigning and Revoking Roles (page 69) topic for more information about calendar roles.

6. Click the alerts page. This page governs whether users receive an alert when an calendar event is created,

modified, or deleted.

Assigning and Revoking Roles

You can further configure an instance of the Calendar Gear by assigning or revoking roles in the gear instance.

The calendar role, together with the permissions setting, determines who can view or create private or public

events. To assign a role:

1. Enter the Community Administration and go to the Current Gear Instances page.

2. Click the Assign/Revoke Roles link for the Calendar Gear.

3. Use the dropdown list and the search feature in step 2 of the Assign/Revoke gear role page to locate the

individual user or organization whose role you want to change.

4. Click the Assign/Revoke Roles link for that individual or organization. Check or uncheck the box for the roles

you want to assign or revoke.

Community Members Gear

Module name: contacts

The Community Members Gear displays a list of the members of the community. The list contains an e-mail

link and a link to the portal profile for each community member. The list is updated as community membership

changes.


To configure an instance of the Community Members Gear:





3. Click the additional configurations link. The additional configurations page has two subpages, display

parameters and sort parameters.

On the display parameters subpage, you can configure how many members are displayed on a shared

view of the gear (where the gear is one of many on the page) and on a full view of the gear (where the gear

occupies the whole page).

On the sort parameters subpage, you can configure the default sorting of members in the list.

Discussion Gear

Module name: discussion

The Discussion Gear lets users participate in threaded online discussions with other users in the community.

Registered users can create discussion boards as well as read, reply to, and post messages. Portal Administrators

and Community Leaders can moderate these forums and edit the discussion boards as necessary.


To configure an instance of the Discussion Gear:




3. Click the additional configurations link. The additional configurations page has five subpages, select/

administer forums, Display Attributes, access controls, alerts, and resource bundle.

select/administer forums: Create and delete discussion boards, and to make discussions from other

communities available in this instance of the Discussion Gear. To create a new discussion board, click the

create new forum link. Enter a name for the new discussion board. Select private to make the discussion

board available only to members of this community. Select public to allow other communities to view the

discussion board in shared instances of the Discussion Gear.

Display Attributes: Set the number of forums and posts and the length of texts that appear in the shared

and full views of the gear.

access controls: Specify which classes of users can post to the discussion boards in this gear instance.

alerts: You can configure whether alerts are generated by the gear instance.

resource bundle: You can change the resource bundle for this gear. You should not need to change the

resource bundle unless this gear instance is intended for a language other than English.

Discussion Gear messageThread Cache

The Discussion Gear maintains forums in a SQL repository. If the messageThread item cache in the repository is

too small, the Discussion Gear’s performance will not scale as the size of the forum or threads increase. The item

cache must be large enough to hold a list of all threads in the forum, and it must be large enough to hold a list

of all replies to a thread in the forum. The default size of the item cache is 1000. The appropriate size for your site

depends heavily on the amount of activity in a forum.

Set the item cache in the definition of the messageThread item descriptor in the Discussion Gear repository

definition file. Set the item-cache-size attribute by including a file like this in your CONFIGPATH at /atg/

portal/gear/discussion/discussionRepository.xml :


<gsa-template> <item-descriptor name="messageThread" item-cache-size="50000"> </item-descriptor></gsa-template>

Document Exchange Gear

Module name: docexch

The Document Exchange Gear lets visitors interact with any document repository. Depending upon their

security permissions, visitors can upload, download, annotate, edit, and share documents with other registered

users in the portal community. Portal Administrators can use security permissions to maintain the integrity

of the document repository. ATG Portal can also use the documents in the repository to create new dynamic

content within the PAF. Portal users can perform keyword searches on the repository using the Repository

Search Gear (page 78).

Configuring a Document Repository

To specify the location of the document repository, you must be a Portal Administrator.

A repository used by the Document Exchange Gear needs to have one item descriptor that corresponds to a

document. The document item descriptor needs to define properties that store the following information:

file name

file data

MIME type

file size

description

title

author

create date

status

gear ID

discussion ID

If you configure the gear to point to your own repository, you should set the maxlength attribute of the

document title and description properties in the repository so that users creating documents are informed if

they attempt to create documents with titles or descriptions that overflow the size of the database column.

These properties are already set in the default document repository. You must do this only if you configure the

gear to use another repository. To set the maxlength attribute, edit the repository definition XML file and add

the maxlength attribute as in this example:

<property name="title" column-name="title" data-type="string"> <attribute name="maxLength" value="254"/></property><property name="description" column-name="description" data-type="string"> <attribute name="maxLength" value="400"/></property>

When you configure the document exchange gear to use a repository other than the default repository and

RQL query, you must tune your database and repository to achieve the best possible performance. For more

information on performance tuning, refer to the ATG Installation and Configuration Guide.


Configuring the Expression Editor

Note that the expression editor in the ATG Control Center is configured to point to the default document

repository, /atg/portal/gear/docexch/SplitDocumentRepository in the /atg/portal/gear/

docexch/docexch-expression-grammar.xml file found in <ATG9dir>/Portal/docexch/lib/

docexch.jar:

...<token> <expression-class>atg.ui.expreditor.targeting.RepositoryItemSetExpression </expression-class> <assistant-class>atg.ui.expreditor.targeting.RepositoryItemSetAssistant </assistant-class> <attribute name="repositoryName" value="/atg/portal/gear/docexch/SplitDocumentRepository"/> <attribute name="repositoryItemType" value="document"/> <required/> <description>Choose document...</description></token>...

If you use a different document repository, you need to modify this token tag in the docexch-expression-

grammar.xml expression editor grammar file to point to the appropriate document repository and document

repository item type. See the Configuring the ATG Expression Editor chapter in the ATG Personalization

Programming Guide for more information about how to modify expression editor grammar files.

Installation Configuration

To configure the Document Exchange Gear in the Portal Administration:

1. Click the configure link for the gear in the Available Gears page. A page opens titled Configure Gear

Definition: Document Exchange.

2. Enter the Nucleus address of the repository that will store the gear’s documents and click Continue.

3. In the Repository Item Type field, select the item type that corresponds to documents in the repository and

click Continue.

4. Map the properties of the selected item type to the properties needed by the gear. Select the property from

the document item descriptor that is used for each of the following:

file name

file data

mime type

file size

description

title

author

create date

status

gear id

discussion id

Click Finish.

5. Click the Repository Limitations link.


6. Select whether the gear exposes the repository as read-only or read/write. If the gear uses a read-only

repository, portal users will not be able to add documents. You can configure an instance of the gear to adjust

the permissions of a read/write gear to limit who can add or modify documents.

7. Set a maximum file size for documents in the repository and click Finish.


To create an instance of the Document Exchange Gear in a community:

1. Enter the Community Administration and click the Select New Gears link in the side navigation panel.

2. Enter a gear name and description.

3. Select sharing and Make visible to options.

4. Click Done.

To configure an instance of the Document Exchange Gear:


2. Click the additional configurations link.

3. Apply the appropriate settings in the appearance page. Click Save.

4. Click the permission link. You can select which groups of portal users are permitted to:

5. Read and discuss documents

6. Add new documents

7. Change the status field for documents

Click Save.

8. Click the functionality link. You can select the features rendered in the Document Exchange Gear instance.

Select Enable Discussion to include the discussion board feature in the gear instance.

Select Enable Search to include a search field in the gear instance. Note that this search field enables

searches only within the documents of this gear instance. For a broader search function, use the Repository

Search Gear (page 78).

Select Attachment Required to require that each new item have a file attachment.

Click Save.

9. Click the alerts link. You can configure whether alerts are sent to users when documents are added, modified,

or deleted in the gear instance.

Virus Protection for the Document Exchange Gear

The Document Exchange Gear allows users to upload files into the portal. There is a risk that some of these files

might contain viruses. The gear does not check for viruses or other unacceptable content. However, it includes a

stub method that a gear developer could override to implement document checking.

The stub method is found in the atg.portal.gear.docexch.DocumentFormHandler class. You can find the

source code for this class at:


<ATG9dir>/Portal/docexch/src/classes.jar/atg/portal/gear/docexch/DocumentFormHandler.java

The stub method is:

public void validateFileContents(UploadedFile pUploadedFile) { // no op }

You can extend the DocumentFormHandler and override this method to reject an uploaded document based

on any criteria. For example, you might implement virus scanning, looking for offensive words, or whatever

checks your application requires. In addition to overriding the validateFileContents method, you should

also add an exception to the file upload form, as in this example:

addFormException( new DropletException(getAbsoluteName() + ".value." + "uploadedFile", "FILE_CONTENT_REJECTED")); */

Announcements Gear

Module name: docexch

The Announcements Gear is just a different version of the Document Exchange Gear. You can install the

Announcements Gear, using the Gears > New Gear page in the Portal Administration interface. Browse to the

gear’s manifest at <ATG9dir>/Portal/docexch/announcements-manifest.xml and upload the manifest.

The Announcements Gear is configured just like the Document Exchange Gear. See the Installation Configuration

and Instance Configuration sections of Document Exchange Gear (page 71).

Favorite Communities Gear

Module name: communities

The Favorite Communities Gear displays a list of the member’s favorite communities. Community Members

can individually configure their own list of favorite communities, or they can display a list of all the available

communities. This provides quick navigation to any community from any page that has an instance of the

Favorite Communities Gear.


To configure an instance of the Favorite Communities Gear:




HTML Content Gear

Module name: screenscraper

The HTML Content Gear retrieves the contents of a Web location, given its URL, then renders the location as gear

content. The gear also ensures that all the URIs in the Web content are properly rewritten so that the links shown

in the gear content point to the original Web server.



To configure an instance of the HTML Content Gear:




3. Click the additional configurations link. The additional configurations page has two subpages, url

settings and alerts.

url settings: Enter the URL of the content you want displayed in the gear. You can also include a URL and link

text for users to display the content in a full page. You can change the resource bundle if you are localizing

this gear instance for a language other than English. If you specify something other than the default, you

must make sure the new resource bundle location is specified in the CLASSPATH.

alerts: Specify whether users can receive alerts from this gear.

Configuring the HTMLFilterParser

The behavior of the HTML Content Gear is also affected by a Nucleus component named /atg/portal/gear/

screenscraper/HtmlFilterParser. This component has three properties that you may want to configure:

tagsToRemove

A list of tags that you want to remove from the source Web page so that those tags from the source page do not

interfere with the rendering of the content into the gear’s content pages. For example, suppose something like

this appears in the source content:

<title>This is the Title</title>

and you have specified title as one of the items in the property tagsToRemove. Then, the above string will be

rendered in the gear’s content pages as This is the title, without the <title> tags.

tagsToRemoveWithBody

A list of tags that you want to remove, together with the tags’ contents, from the source Web page. This does

the same thing as the tagsToRemove property, except that it will remove not just the specified tags but also

anything between the start and end tags.

For example, if this appears in the source content:

<title>This is the Title</title>

and you specified title as one of the items in the property tagsToRemoveWithBody, then whole string will be

removed, including both the <title> tags and the This is the title string.

replaceBodyTagWithTableTag

The parser replaces the <body> tag with a <table> tag so that the community page where the gear is

installed is not messed up due to the bgcolor or background attributes of the source page’s <body>tag. This

functionality can be turned off by setting the replaceBodyTagWithTableTag property to false.

Extending the HtmlFilterParser

The Portal module includes the source code for the atg.portal.gear.screenscraper.HtmlFilterParser

class in the <ATG9dir>/Portal/screenscraper/src/classes.jar/atg/portal/gear/screenscraper


directory. You can modify the class to do your own custom parsing. You can even replace this parser with

a parser of your own by subclassing the atg.portal.gear.screenscraper.HtmlFilterParser and

overriding the parse(Reader pIn, Writer pWriter) and parse(InputStream pIn, OutputStream

pOut) methods. This might enable, for example, the capability of replacing other tags in the source page.

Login Gear

Module name: user_registration

The Login Gear provides a secure interface for visitors to log in to the community. Visitors must login using this

gear before they can assume their roles within the community.


To configure an instance of the Login Gear:




3. Click the additional configurations link. Here, you can configure some optional behavior for the login page:

Show registration message and link?: If true, the login page offers users a link that allows them to register

for the portal. Set this to false if you do not want to allow new members to register and join.

Flag to show username on shared view when logged in: If true, the portal displays the user’s username.

page to forward to after login: By default, the login page returns the user to the current page after login.

You can specify the URL of a different page here.

Click Finish.

The gear is updated to use the new settings and information.

Outlook Gear

Module name: exchange

The Outlook Gear gives visitors access to their Microsoft Outlook account. Visitors can use this access to send

and receive e-mail from within the portal.


You can configure the Web Access Host and Proxy Servlet Host settings in an installation configuration of the

Outlook Gear. To configure the Web Host and Proxy Host settings of your MS Outlook server you must be a

Portal Administrator.

To configure the Outlook Gear in the Portal Administration:

1. Click the configure link for the gear in the Available Gears page. A page opens titled Configure Outlook

Server URLs.

2. Enter the Web Access Host URL. The form of your URL may vary depending on the settings chosen by your

Web Access Administrator.


3. Enter the SSL Proxy Servlet Host URL. This is used to transmit user ID and password information using a

separate SSL encoded instance of ATG. If you are using an SSL secured session of ATG, provide the URL for that

other session here. To use the SSL secured session, your MS Exchange Web Access settings must allow basic

authentication. If you are not using SSL encoding, enter the same URL that you used for the Web Access Host.

4. Click Update.



You can configure the descriptive information and access settings in an instance configuration of the Outlook

Gear.

1. Enter the Community Administration. Click the Community Gears tab to view the Configure Gear Instances

page.

2. Click the Configure link next to the Outlook Gear name.

The Configure Gear: Outlook Page opens.

3. Enter a gear name and description. Select sharing and Make visible to options.

4. Click Done.

The gear is updated to use the new information.

Logging In to the Outlook Gear

If a visitor enters an invalid username and password into the login fields for the Outlook Gear, the community

pages still render the Outlook Gear with Inbox, Calendar, Contacts, and Task links. If the visitor clicks on these

links, the visitor is asked to login again. Any attempts, however, to login from this location fail, even if the login

information is valid. The visitor must return to the community page, click the Edit button in the gear title, and re-

enter the login information in the Gear Configuration Pages.

Poll Gear

Module name: poll

The Poll Gear asks a single question, and presents a visitor with a set of responses. Visitors can respond to the

poll question, and view the results of the previous respondents.

You can configure the following settings in an instance configuration of the Poll Gear:

• Gear name and description

• General administration settings

• Access settings

• Poll parameters


You can configure the descriptive information and access settings in an instance configuration of the Outlook

Gear.



page.

2. Click the Configure link next to the Poll Gear name.

The Configure Gear: Poll Page opens.


4. Click Done.

5. Click additional configurations. This page has five parts: set current poll, create new poll, available polls,

resource bundle, and alerts.

set current poll: Select one of the existing polls to be displayed in the Poll Gear instance.

create new poll: Enter a poll title and a poll question. Also enter the possible answers to the poll; all polls

must be multiple choice.

available polls: This page displays all polls available for this gear. You may view poll results, edit an existing

poll, clear votes (returning the vote totals to zero), or delete a poll.

resource bundle: If you have localized the Poll Gear, you can change the resource bundle used for it.

alerts: You can configure whether alerts are generated by the gear instance.

Quicklinks Gear

Module name: quicklinks

The Quicklinks Gear provides a list of bookmarks for the community, created and customized by the Community

Leader.

To configure the Quicklinks Gear:


page.

2. Click the Configure link next to the Quicklinks Gear name.

The Configure Gear: Outlook Page opens.


4. Click Done.

5. Click the additional configurations link. Enter the URL and link text for each link appearing in the gear and

click Save.


Repository Search Gear

Module name: search

Several of the baseline gears store content in a SQL Repository. These gears are the Document Exchange

Gear (page 71), the Discussion Gear (page 70), and the Calendar Gear (page 68). The Repository Search


Gear lets users search by keywords for content in all instances of these repository-based gears in the portal at

once. The user can also restrict a search to the current community or page.


The installation configuration for the Repository Search Gear consists of two parameters that are designed to

make sure that a search doesn’t return an excessively large result set or absorb an excessive amount of system

resources:

Parameter Default

Maximum Results Per Repository 10

Maximum Number of Gears to Search Per Repository 25


The additional configurations page for an instance of the Repository Search Gear allows you to set parameters to

make sure a search doesn’t return an excessively large result set, per page or in total:

Parameter Default

Maximum Results Per Page 10

Maximum Total Search Results 100

Repository View Gear

Module name: repview

The Repository View Gear displays a read-only view of items from any repository. Display can be automatic or

highly customized. The items displayed are selected by configurable targeters.

Repository and Targeter Configuration

The Repository View Gear requires an existing repository. The gear displays items of one type from the

repository you specify. You need to create targeters keyed to that repository and repository item type so that the

gear can determine which repository items to display. See Setting Up Targeting Services in the ATG Personalization

Programming Guide for information about creating targeters.


To configure the Repository View Gear in the Portal Administration:

1. Click the configure link for the gear in the Available Gears page. The configuration page opens, presenting

the following seven steps in configuration: repository, delegate, resource bundle, featured item, short list,

full list, display item.

2. Click the repository link. Enter the Nucleus address of the repository whose items the gear will display and

click Continue.


Select the item descriptor of the type of repository items this gear will display and click Update.

3. Click the delegate link. Check the box if you want to enable community leaders to configure each instance

of this gear independently. Please note that the configuration is somewhat technically oriented and gives a

higher than normal level of access to the data and repositories. It is not recommended to enable delegated

configuration for non-technical or untrusted community leaders.

4. Click the resource bundle link. If you want to change the gear’s user-visible text, because you want to

change its labeling or because you have localized the Repository View Gear, you can specify the resource

bundle to use.

5. An instance of the Repository View Gear can be configured to display a single featured item, a short list of

selected items, or a full list of all items in the repository. The next three steps, featured item, short list, and

full list, let you configure which targeters are used to select the items and which properties of the items are

displayed in each of these views.

6. Click the featured item link.

Select a targeter that chooses which item to display as the featured item.

There are two ways to configure how the gear displays the properties of a featured item. Either enter

the relative pathname of a custom JSP fragment that displays the item properties you want, or enter the

names of the properties that should appear in the featured item display and the gear will create the display

automatically.

Two sample JSP fragments are included in <ATG9dir>/Portal/repview/src/repview.war/html/

content/custom. If you create a custom JSP fragment, specify its pathname is relative to the <ATG9dir>/

Portal/repview/repview.war/html/content/ directory. For example, if you put your custom JSP

fragment in the same directory as the two sample fragments, enter custom/mycustom.jsp.

Click Update.

7. Click the short list link.

Select a targeter that chooses which items to display in the short list of items in the shared view of the gear.

Enter the names of the properties that should appear in the short list of items.

Click Update.

8. Click the full list link.

Select a targeter that chooses which items to display in the full list of items in the full page view of the gear.

Enter the names of the properties that should appear in the full list of items in the full page view of the gear.

Click Update.

9. Click the display item link. When a user clicks on an individual repository item to view it, the gear displays the

properties you select on this subpage. As with the featured item, you can choose either to create a custom

JSP page to display the selected item, or select the properties you want to display and the gear will create the

display automatically.

Click Update.


To configure an instance of the Repository View Gear:





3. Click the additional configurations link. If, in the installation configuration, the Portal Administrator did not

enable delegation of configuration, then this page has two parts: functionality and appearance. If this gear

uses delegated configuration, then the additional configurations page also includes featured item, short

list, full list, and display item.

4. Click the functionality link. Specify whether you want the shared view of the gear to display one or more of a

featured item, a short list, a link to the full list. Click Update.

5. Click the appearance link. Here you can configure how the gear displays times and dates, whether the gear

uses column headers for property names, and whether items are displayed with a link to the full item.

6. The featured item, short list, full list, and display item subpages of the Instance Configuration are

displayed only if the Portal Administrator has enabled delegated configuration in the installation

configuration of the gear. These subpages are identical to the same pages described in the Installation

Configuration topic above.

User Configuration

An instance of the Repository View Gear provides an Edit button that portal users can click to set the maximum

number of items displayed in the full and shared views of the gear.

Targeted Content (Slot) Gear

Module name: slotgear

The Targeted Content Gear lets you display targeted content to portal users, using an ATG Relationship

Management Slot component. Slots are often used to show images, but you can use them to display

any repository items that you choose. See Using Slots section of the Creating Scenarios chapter in the ATG

Personalization Guide for Business Users for an introduction to slots, and Using Slots in the ATG Personalization

Programming Guide for a more detailed view of creating slots.


There is no installation configuration for the Targeted Content Gear itself. Note, however, that you may need

to create slot components for the Targeted Content Gear to use. Use the ACC to create a slot component, as

described in Using Slots in the ATG Personalization Programming Guide. You also need to create a SQL content

repository to contain the content rendered in the Targeted Content Gear.

Targeted Content Gear Repository Configuration

When you configure a slot component, you specify a repository name and an item descriptor name. This defines

what type of item the slot will display. How the item is rendered depends on the item’s media type (i.e. text,

image, or a product). The Targeted Content Gear includes a Nucleus component that defines a mapping of

repository item descriptors to the JSP files that are used to render that particular item type. The Nucleus address

of this component is /atg/portal/gear/slotgear/SlotConfiguration. The slotPages property of the

SlotConfiguration component contains this map. The default configuration (properties file) that is installed

with the gear is shown below:

%cat SlotConfiguration.properties# Version: $Change: 234577 $$DateTime: 2002/04/03 09:25:14 $


# Global configuration properties for the portal$class=atg.portal.gear.slotgear.SlotConfiguration$scope=global# A mapping of itemDescriptorNames used for slots to jsp pages used to render themslotPages=\ media=mediaInternalBinary.jsp,\ media-internal-binary=mediaInternalBinary.jsp,\ media-internal-text=mediaInternalText.jsp,\ media-external=externalMedia.jsp,\ product=productSlot.jsp

When you design the repository that holds content for the Targeted Content Gear, you must either:

• Use one or more item descriptors named media, media-internal-binary, media-internal-text,

media-external, or product.

• Configure the slotPages property to include a mapping of the item descriptor names you use in your slot

content repository to the JSP pages used to render them in the Targeted Content Gear.

In addition, you may want to customize one of the JSP pages used to render content in the Targeted Content

Gear. These JSP files are located in <ATG9dir>Portal/slotgear/slotgear-war.


The Configure Basics page for an instance of the Targeted Content Gear allows you to configure the usual gear

basics:

Gear Name

Gear Description

Sharing

Make visible to

The additional configuration page for the Targeted Content Gear has three steps:

1. Click the define slot link.

Select the name of the Nucleus component for the slot. The dropdown list includes all slot components

that are created in the ACC or otherwise created in the CONFIGPATH at /atg/registry/Slot. The slot

component defines the repository and item descriptor from which it derives repository items to display.

Enter the pathname of an image to display if the slot is empty. Click Save.

2. Click the targeting params link. A slot can use a targeting servlet bean that applies a set of targeting rules to

a repository, retrieves a result set of repository items, and renders one or more of the repository items in the

page region allocated to the slot.

On this page, you can set the input parameters for the targeting servlet bean that renders the slot. For

information about these parameters, see the description of the TargetingFirst, TargetingForEach,

TargetingRange, or TargetingRandom servlet beans in the ATG Page Developer’s Guide.

After you configure the input parameters for the targeting servlet bean, click Save.

3. Click the property names link. A slot renders an image or text from a repository item. The URL property

defines the property in the repository item that points to the location of an image on the file system. The data

property represents text to be displayed in the slot.

The external media context root property is used to specify the root for external media item types. In the

baseline Slot Gear, the external media you are using need to exist inside the Slot Gear Web application.


After you configure the property names, click Save.

Web Services Client Gear

Module name: soapclient

The Web Services Client Gear enables portal visitors to access Web services made available on remote

computers. A Web service application can describe itself, publish this description to a directory, and be invoked

remotely over a network via Simple Object Access Protocol (SOAP). The Web Services Client Gear acts as a client

in Web service transactions.

For example, there might be a Web service that exposes the top five news headlines for a given topic. A client

of this service would provide a topic (technology, financial, entertainment etc.) that it would like the top five

headlines for. The server exposing this service would then return the matching headlines. In this example, the

Web Services client gear provides the ability for a portal user to configure the gear to connect to the service as

well as provide the topics that should be obtained from the server. These headlines will then be displayed on a

given portal page where the gear is deployed.

There are several restrictions on the type of Web services and Web Services Description Language (WSDL)

documents that the gear can handle. The gear can only support the invocation of services where the types of

the parameters to the service as well as the return value are simple types. The following types are supported:

• string

• integer

• byte

• short

• boolean

• long

• float

• double

These types are expected to be declared in the WSDL document as the associated schema data type.

Additionally, a WSDL document that is to be uploaded can contain only the definition of a single method for a

service.

There are two types of configuration information that must be supplied in order to successfully invoke a Web

service:

• Protocol-level connection information

• Runtime values to pass as parameters to a service

Using the above example, protocol-level connection information would be things like a URL to connect

to and a method name to invoke. The runtime parameter would be the news topic you are requesting.

Configuring protocol-level connection information is a technical task and thus is the responsibility of the Portal

Administrator. Each user will then want to customize the parameters passed to a given service in order to

personalize the service. Thus, the Web Services client gear can be configured at both the Portal Administrator

level as well as user level.



Before the gear can be successfully used, it must be configured with its connection-level information. The

installation configuration is the only place that this can be done. The information that must be supplied

is information that is specific to SOAP (the RPC layer in the Web Services protocol) as well as the transport

information that the SOAP message will be sent over. The Web Services gear supports invoking Web Services

over the HTTP-based protocol.

The following SOAP connection information is required:

Method name The method name that is to be invoked on the remote service

Parameters The name and type of the parameters that are to be supplied to a

particular method

URI of target object The URI for the remote service

The following HTTP connection information is required:

Target URL The URL where the remote service is located

SOAP Action Value that can be placed into HTTP header to indicate intent

Web services provide a way to describe this information in a single document. This is done via the Web Services

Description Language (WSDL). The WSDL specification provides a standard way to model the definition of a

particular service. The modeling is done via an XML document. Typically, any Web service that is available will

provide a WSDL document that describes the service. The Web Services gear only needs this WSDL document

in order to know its connection information. It will take this WSDL document and parse out all of the SOAP- and

HTTP-specific information. To configure the gear with this WSDL document follow these steps:

1. On the Gears tab of the Portal Administration Pages click the configure link next to the Web Services Client

Gear name.

2. Browse to the location of the WSDL document on your machine and then click Upload.

This will upload the WSDL document from your local machine to the server. The server will then attempt to

extract all of the necessary connection information from this document. If any errors occur then the user will

remain on the same page and the errors that resulted will be displayed.

Each user must now customize the values of the parameters to pass to the Web service by using the User

Configuration pages. For example, the user must specify what type of news headlines to receive.

User Configuration

Users set the value of the parameters to pass to a given service. They are personalizing the service to obtain the

information that interests them.

In the News Service example, if the Portal Administrator has uploaded a WSDL document describing the service

to connect to (News), then the gear has all the information necessary to connect to the service. In addition, the


News Service has defined a single parameter for the service, newsTopic. Before the gear can successfully invoke

the News Web service, it must know what newsTopic it should request the headlines for. It is up to the user to

set the runtime values to pass to a particular service. While these values could be supplied in a variety of ways

(form input, user configuration, JSP value passing, etc.) the Web Services gear only supports configuration of

runtime parameters through the user configuration pages.

The user configuration page will expose form input fields for each parameter that can be passed to a particular

service. The name and number of these parameters will vary depending on the service you are invoking.

The service pages are built up dynamically depending on the WSDL document that the gear installation

configuration was supplied with. The user configuration pages will determine all the parameters from the WSDL

document that was previously uploaded and then generate the form input on the fly. So, for the News Service

the user configuration page would expose a single input box. The name for this input box would be News

Topic and then the user would be expected to type in the News topic that they wanted to receive headlines for:

financial, technology, etc.

To configure the value of the parameters, follow these steps. (This assumes that the Gear has been installed onto

a particular community page).

1. In the Web Services gear, click the edit button.

The user configuration page for the gear opens.

2. Enter or set the appropriate values.

3. Click the done button.

XML-Feed Gear

Module name: xmlfeed

The XML-Feed Gear uses XSL-Transformation to display content from a local or remote XML file according to

the transformation rules provided by a local or remote XSL file. This gear can serve as a simple XSLT gear or can

display content from various external content providers. For example, an instance of the XML-Feed Gear can be

configured to act as a real-time stocks, weather, or news gear.

The XML-Feed Gear uses the standard Jakarta Xtags tag library. You should enable gear caching to optimize gear

performance for gears that utilize XML parsing. Gear caching is enabled by default for the sample XML Feed

Gear. Gear caches use time-based expiration so any changes made to the underlying XML file are reflected in the

user’s portal experience once the cache timeout expires.

You can have more than one XML-Feed Gear on a page, with each gear receiving a different feed.

Configuring the XML-Feed Gear for Simple XSLT

Point the XML and XSL sources to the appropriate location. The Stocks, Weather and Business-News versions of

the XML-Feed Gear in the Content Syndication Gear Folder are good examples of how to use this gear for simple

XSLT.

Configuring the XML-Feed Gear for External Content Providers

The XML-Feed Gear provides a framework for configuring it with various external XML content providers. The

gear users can customize the content. These customization parameters are mapped to the URL of the XML

source. For more information on gear parameters and customization, refer to the ATG Portal Development Guide.


You can configure the source feed installation settings of the XML-Feed Gear.


1. On the Gears tab of the Portal Administration Pages click the configure link next to the XML-Feed Gear name.

The Xmlfeed Gear Install Configuration Page opens.

2. Set the following source feed and output parameters:

Base XML Source:

Additional Query Parameters Mapping:

XSL Source for Shared Mode, HTML Output:

XSL Source for Full Mode, HTML Output:

XSL Source for Shared Mode, WML Output:

XSL Source for Full Mode, WML Output:

Show a link to the full mode in shared mode: Enter true if you want the shared display mode version of the

gear to include a link that opens the gear in full display mode.

3. Click Update.

The gear is updated to use the new settings.


The Configure Basics page for an instance of the XML-Feed Gear allows you to configure the usual gear basics:

Gear Name

Gear Description

Sharing

Make visible to

The additional configuration page for the XML-Feed Gear allows you to configure each of the source feed and

output parameters that you can configure in the Portal Administration’s installation configuration for the gear:

Base XML Source

Additional Query Parameters Mapping

XSL Source for Shared Mode, HTML Output

XSL Source for Full Mode, HTML Output

XSL Source for Shared Mode, WML Output

XSL Source for Full Mode, WML Output

Show a link to the full mode in shared mode

XML Protocol Gear

Module name: xmlprotocol

The XML Protocol Gear communicates with external XML-based service providers. The gear can retrieve and

display XML documents such as headlines, categories, or articles from service providers such as syndicated news

services. The XML Protocol Gear can communicate with stateful or stateless service providers.



The Configure Basics page for an instance of the XML Protocol Gear allows you to configure the usual gear

basics:

Gear Name

Gear Description

Sharing

Make visible to

The additional configuration page for the XML Protocol Gear has two subpages: Edit gear configuration and

Edit user defaults.

Edit gear configuration

The Edit gear configuration subpage allows you to configure the source of the XML service and the stylesheets

used to display the XML provided by the service:

Instance Authentication Parameters

User ID: The user ID required to access the XML service provider.

Password: The password associated with the user ID required to access the XML service provider.

Service Configuration Parameters

Service provider: Enter the name of the adapter class for communicating with a provider service. The default is

atg.portal.gear.xmlprotocol.GenericXPathAdaptor. You need to create a new adapter class for each

service provider you want to communicate with. See Creating New Adapter Classes (page 88) for information.

Enter the URL required by the service provider (including an appropriate port number, if any) for each of the

following:

Authentication URL: The URL for authenticating with the service provider.

Categories URL: The URL for retrieving a list of categories from the service provider.

Headlines URL: The URL for retrieving headlines from the service provider.

Article URL: The URL for retrieving articles from the service provider.

Feed Display Configuration Parameters

Enter the URLs of XSL stylesheets for full and shared views of content from the service provider:

Full View Categories Stylesheet URL

Full View Article Stylesheet URL

Full View Headlines Stylesheet URL

Shared View Categories Stylesheet URL

Shared View Headlines Stylesheet URL

The gear includes a set of example XSL stylesheets for each of these content view categories. The stylesheets can

be found in the /xmlprotocol/src/xmlprotocol.war/templates folder.

Edit user defaults

The Edit user defaults subpage allows you to configure the default display options for users. The parameters

you can set are:


Number of headlines to display in shared mode

Number of headlines to display in full mode

Categories to display

Creating New Adapter Classes

The XML Protocol Gear requires a Java adapter class to be generated for each service provider it communicates

with. The gear includes a base class, XpathBaseAdaptor, that you can use in combination with an XSLT

stylesheet to generate the adapter class. To generate an adapter class:

1. Create an adapter manifest file. Base this manifest file on the example at <ATG9dir>/Portal/

xmlprotocol/src/etc/adaptor.definitions/GenericXPath-manifest.xml. Enter values

appropriate for the service provider in the fields of the manifest file.

2. Perform an XSLT transform, using the XSLT stylesheet found at together with your adapter manifest file.

3. Compile the resulting Java class and put it in your CLASSPATH.

4. When you create an instance of the XML Protocol Gear for this service provider, enter the class name of the

adapter class in the Service Configuration Parameters: Service provider field of the Edit gear configuration

page.

Index 89

Index

Aalerts

configuring, 49, 50

configuring e-mail, 17

creating, 49

deleting, 50

Alerts Gear, 67

Announcements Gear, 74

anonymous access, 22

Bbaseline gears, 65

Alerts Gear, 67

Announcements Gear, 74

Bookmarks Gear, 68

Calendar Gear, 68

Community Members Gear, 69

configuring, 66

Discussion Gear, 70

Document Exchange Gear, 71

Favorite Communities Gear, 74

HTML Content Gear, 74

Login Gear, 76

Outlook Gear, 76

Poll Gear, 77

Quicklinks Gear, 78

Repository Search Gear, 78

Repository View Gear, 79

Targeted Content Gear, 81

Web Services Client Gear, 83

XML Protocol Gear, 86

XML-Feed Gear, 85

Bookmarks Gear, 68

branding, 13

business rules, 13

CCalendar Gear, 68

cascading stylesheets (see stylesheets)

color palettes, 45

adding, 46

Communities, 19

copying from templates, 30

creating, 21, 24

deleting, 27

disabling, 27

editing, 27

Guests, 22

Leaders, 22

Members, 22

membership, 23

role IDs, 23

Community Administration pages, 8

color palettes, 44

community gears tab, 9

community members tab, 37

community pages tab, 9

community settings tab, 9, 23

community users tab, 9

layout templates, 44

page layouts, 44

reset buttons, 9

security, 63

Community folders, 20

creating, 20

deleting, 20

Community Guests

adding, 39

Community Leaders

adding, 39

Community Members

adding, 37

approving or declining, 38

enabling membership request notification, 38

Community Members Gear, 69

Community pages

adding, 28

adding gears, 29

deleting, 30

editing, 28

viewing, 29

community proposals, 33, 34

creating, 36

scenarios, 36

workflows, 35

Community roles, 21

community templates, 30

creating, 31

creating new users, 40

customization administration, 50

Ddatabase

90 Index

configuring, 11

default Portal, 4

Discussion Gear, 70

item cache, 70

Document Exchange Gear, 71

virus scanning, 73

FFavorite Communities Gear, 74

Ggear administration, 46

gear folders, 47

gear title templates, 14, 45

adding, 45

titlebar-post.jsp, 15

titlebar-pre.jsp, 15

titlebar.jsp, 14

gears

adding to the PAF, 48

baseline, 65

deleting, 48

installation configuration, 47

instance configuration, 47

limiting access by communities, 26

parameter configuration, 47

sharing, 48

HHTML Content Gear, 74

configuring parser, 75

HtmlFilterParser component, 75

Iindividuals, 19

internationalization, 16

JJ2EE security, 59

Llayout templates, 14, 44

100.jsp, 14

25_50_25.jsp, 14

25_75.jsp, 14

75_25.jsp, 14

adding, 44

creating, 15

LDAP profile repositories

searching for users, 40

localization, 16

Login Gear, 76

Mmanifest files, 43

Oorganizations, 19

Outlook Gear, 76

Ppage templates, 13, 44

adding, 44

full page template, 14

shared page template, 14

performance

Scenario Server, 17

Poll Gear, 77

Portal

development basics, 4

Portal Administration pages, 5, 24

Alerts tab, 7

color palettes, 7

communities tab, 6

community members tab, 24

gear title templates, 7

Gears tab, 6

launching, 4

layout templates, 7

page templates, 7

security, 63

Styles tab, 7

stylesheets, 7

Portal Administrator, 22

Portal Process Automation, 33

Portal.<gearname>, 2

Portal.gears module, 2

Portal.paf module, 1

Profile repository, 12, 12

profile template, 12

QQuicklinks Gear, 78

Rregion.jspf, 14

registered user, 22

relative roles, 22

repositories

configuring, 11

creating, 11

profile, 12, 12

Repository Search Gear, 78

Repository View Gear, 79

roles

Index 91

Community, 21

Community Leader, 22

Community Member, 22

global, 22

IDs, 23

relative, 22

Sscenarios, 13

scenarios for community proposals, 36

security, 59

administering, 59

secured areas, 63

security levels

see access levels, 60

Slot Gear (see Targeted Content Gear)

SlotConfiguration component, 81

SpawnCommunity tool, 31

stylesheets, 46

adding, 46

TTargeted Content Gear, 81

repository configuration, 81

SlotConfiguration component, 81

templates

gear title, 45

layout, 44

page, 44

Uuser profiles

creating, 40

WWeb Services Client Gear, 83

workflows for community proposals, 33, 35

XXML Protocol Gear, 86

adapter classes, 88

XSL stylesheets, 87

XML-Feed Gear, 85

92 Index

atg portal administration guide - product version: 9 · portal.war paf the default portal in...

Documents